🧪 Beta — 能力已可用，接口契约可能微调。

接入 Authing

本页讲如何把 Authing 配置为 GenAuth 的 Human IAM Provider。对接形态与 F1 整合原理中的三个能力面一一对应：目录读取（用户是谁）、联邦登录（用企业账号确认授权）、权限评估（用户能做什么）。

读完本指南，你将：

理解 Authing provider 的对接形态：OIDC 联邦登录 + 目录/权限读取分别解决什么问题
完成租户与访问凭证的基础配置，并验证用户目录绑定对委托签发生效
掌握私有化同域旁挂部署下的对接要点

对接形态一览

能力面	回答的问题	状态
用户目录绑定	被委托人是否真实存在于目录	🧪 Beta（随委托签发生效）
OIDC 联邦登录	授权确认（Consent）时，用户用哪个账号登录	🚧 Roadmap
目录/权限读取	人的真实权限——三方交集的缩权下界	🚧 Roadmap

前置条件

GenAuth 侧：租户与访问凭证（AK/SK）。租户与凭证的创建、轮换走 /api/v3/eak/tenants 系列端点，完整契约见 API Reference。
Authing 侧：一个作为用户权威来源的用户池（用户目录）。
部署形态差异：SaaS 形态下，委托用户目录由租户托管，目录绑定开箱即用；私有化同域旁挂形态下，目录权威在你域内的 Authing——本页其余内容以私有化旁挂为主线，形态差异详见部署形态。

绑定用户目录：委托从"确认这个人存在"开始

目录绑定是 Authing provider 当前已生效的对接面：租户初始化时绑定用户目录后，每一次委托请求中的用户都以该目录为权威来源——签发前，GenAuth 会核验被委托人在目录中真实存在，不存在的用户拿不到任何委托令牌（Delegate Token）。

对你的代码来说没有额外动作：正常发起委托即可，目录核验发生在 GenAuth 内部。

import { Qoni, AnimaScopes } from "@eazo/anima";

const anima = new Qoni({
  host: "https://api.eak.eazo.ai",
  accessKey: process.env.ANIMA_ACCESS_KEY!,
  secretKey: process.env.ANIMA_SECRET_KEY!,
});

// 对目录内的真实用户发起一次 interactive 委托
const { data } = await anima.delegateToken({
  mode: "interactive",
  agent: "report-agent",
  scopes: [AnimaScopes.WEB_SEARCH_RUN, AnimaScopes.WEB_SEARCH_READ],
  redirectUri: "https://yourapp.example.com/callback",
  state: "opaque-state",
  user: { id: "usr_demo_0001" }, // 以你目录中的用户标识为准
});
// data.authorizationUrl —— 交给用户完成授权确认

完整的委托闭环（回调、拿令牌、令牌兑换）见第一次委托：30 分钟跑通。

配置 OIDC 联邦登录

🚧 Roadmap — 本小节描述的能力尚在路线图中，概念与设计已定型，接口与操作步骤以正式发布为准。

联邦登录解决授权确认页的"进门"问题：用户点开授权确认页时，跳转到 Authing 用企业账号完成认证，身份断言回到 GenAuth——站在确认页前的人，与目录里的人是同一个人。对应完整旅程的第 ⑧ 跳：

对接采用标准 OIDC 授权码流程。届时你需要在 Authing 侧准备一个 OIDC 应用，并把以下概念参数交给 GenAuth（具体配置入口以正式发布为准）：

概念参数	作用
Issuer（签发方地址）	GenAuth 发现 Authing 的 OIDC 端点
应用 ID / 应用密钥	GenAuth 作为 OIDC 客户端的身份
回调地址（Redirect URI）	认证完成后身份断言回到 GenAuth
请求 scope（`openid profile` 等）	决定身份断言携带哪些基础 claim

联邦登录生效前，授权确认页的登录使用 GenAuth 域内的用户目录会话完成。

配置目录/权限读取

🚧 Roadmap — 本小节描述的能力尚在路线图中，概念与设计已定型，接口与操作步骤以正式发布为准。

权限读取回答三方交集里"人的真实权限"这个集合（原理见 F1 层次二与委托令牌与缩权）。对接形态：GenAuth 经 provider 以只读方式评估用户在 Authing 目录中的权限断言（角色、组、权限点），断言只用于收窄委托、不反向写回。三条硬边界与 F1 一致：只读、实时、取交集不放大。

私有化同域旁挂：对接要点

私有化形态下，GenAuth 以微服务组件旁挂进 Authing 所在的 k8s namespace（完整形态图与边界矩阵见部署形态）。对接时盯住四件事：

流量不出域——联邦跳转与目录/权限读取全部走域内流量，用户凭证与权限数据不出客户边界；
同域回调——授权确认页与 Authing 登录页同域或互信域，避免跨域跳转在企业浏览器策略下被拦截；
凭证边界——GenAuth 持有的只是面向 provider 的只读凭证；服务间调用认证（mTLS、Secret 管理）按 G2 的服务间调用认证矩阵执行；
air-gapped 可用——离线部署下 provider 对接同样完全在域内完成，无外部依赖。

验证

委托闭环走完后，用发布版 SDK 的 introspect 核对令牌的身份归属：

const info = await anima.genauth.introspectDelegationToken({ token });
// 核对：sub（人，来自你的目录）、agent_id、scope、grant_id、audit_id

sub 应指向你目录中发起授权的那个用户——这就是目录绑定生效的直接证据。完整 claim 字段表见 Token 与 Claim 参考。

常见问题

我必须把用户迁移到 GenAuth 吗？ 不用。目录权威始终在你的 Authing 用户池，GenAuth 只读取与核验，不接管、不写回。这是 F1 说的"打通不是迁移"。

委托签发时提示用户校验失败？ 先核对 user.id 是否来自绑定的那个目录——最常见的原因是拿了别的系统的用户标识来发起委托。目录里不存在的用户，GenAuth 会在签发前拒绝。

现在就能配联邦登录吗？ 还不能，该小节为 Roadmap。当前授权确认页的登录由 GenAuth 域内的用户目录会话完成；正式发布后，将支持跳转 Authing 以企业账号认证。

我用的不是 Authing，怎么办？ Azure AD（Entra ID）、Okta 与标准 OIDC 的对接形态见 F3——Provider 抽象保证对接方式是同一套语言。

下一步

上手：第一次委托：30 分钟跑通 —— 完整跑一遍委托闭环
架构：部署形态 —— 私有化同域旁挂的数据边界与调用认证矩阵
参考：API Reference —— 租户、凭证与委托端点的完整契约

接入 Authing ​

对接形态一览 ​

前置条件 ​

绑定用户目录：委托从"确认这个人存在"开始 ​

配置 OIDC 联邦登录 ​

配置目录/权限读取 ​

私有化同域旁挂：对接要点 ​

验证 ​

常见问题 ​

下一步 ​