🧪 Beta — 能力已可用，接口契约可能微调。
接入你已有的认证体系
不需要更换你现有的身份系统。
这是本页要回答的唯一问题。企业买身份类产品最大的顾虑从来不是"这个功能有没有"，而是"我上一套 IAM 花了两年，你别叫我推倒重来"。GenAuth 的定位是在你既有的 Human Identity 体系上加一层——用户还在你的目录里，登录还走你的流程，改变的只是"Agent 从哪里拿到权限"。
读完本指南，你将能够：
- 判断你的情况该走哪条接入路径
- 知道每条路径需要你配什么、我们负责什么
- 清楚两条路径各自的安全边界与代价
两条路径，先选一条
| 路径 A：OIDC 身份联邦 | 路径 B：服务端信任 | |
|---|---|---|
| 一句话 | 用户在你熟悉的登录页完成认证与授权确认 | 用户在你的应用里已登录，由你的服务端以组织名义发起委托 |
| 用户体验 | 有一次跳转（到你的 IdP 登录 → 授权确认页） | 无跳转，用户不额外操作 |
| 谁在同意 | 终端用户亲自 | 组织（管理员预先同意） |
| 需要你有 | 一个支持 OIDC 的身份提供方 | 一套可信的服务端登录体系 |
| 适合 | 面向个人数据与操作、需要用户知情 | 后台任务、批处理、已有成熟登录体系的自有应用 |
| 主要代价 | 交互往返，需要用户在场 | 密钥即权力，加固要求高 |
选不定时的判断法：这次授权如果用户事后不知情会不会不合适？会，走 A；不会（比如夜间对账），走 B。
路径 A：OIDC 身份联邦
它解决什么
用户身份的权威留在你的 IdP。GenAuth 不再自己养一份用户，而是在授权确认时把用户送回你的登录页——用户看到的是自己熟悉的登录界面，认证完成后回到授权确认页做决定。
同时打通两件事：
- 身份联邦：用户是谁（
sub指向你目录里的那个人） - 权限读取：用户能做什么（决定委托的上界，即缩权三方交集里"人的真实权限"这一项）
你需要配什么
- 在你的 IdP 里为 GenAuth 注册一个 OIDC 客户端（授权码模式），配置回调地址
- 决定 scope 与 claim 映射：GenAuth 需要能拿到稳定的用户唯一标识
- 在 GenAuth 侧配置 provider 连接（当前支持的 provider 与规划见 整合原理）
- 验证：走一次完整的 interactive 委托（见 快速开始），确认授权确认页上的用户就是你目录里的那个人
边界
- 你的 IdP 是身份权威，GenAuth 不复制、不接管你的用户目录
- 用户禁用/离职在你的 IdP 侧生效后，后续授权确认自然失败
- 权限读取的具体形态取决于 provider 能力（见 整合原理）
路径 B：服务端信任
它解决什么
你的应用已经知道"当前是谁在用"——用户刚在你的系统里登录过。再把他赶去一次授权页，体验上多此一举，产品上还可能被业务方否决。
这条路径下，组织管理员预先以组织名义同意"本组织的这类 Agent 可代本组织用户执行这些 scope"，此后你的服务端持访问密钥直接发起委托，无需用户逐次确认。
// 你的服务端已确认当前登录用户，直接发起委托
const { data: grant } = await anima.delegateToken({
agent: "report-agent",
scopes: [AnimaScopes.WEB_SEARCH_RUN], // 最小集合
user: { id: currentUser.id }, // 来自你自己的登录态
expiresIn: 900, // 15 分钟，按任务给
});你需要做什么（不是可选项）
这条路径等同于以组织名义授权
持有访问密钥的一方可以为组织内的用户发起委托。访问密钥泄露即组织级风险。 采用前必须落实：
- 密钥只存在于服务端受控环境（密钥管理服务/环境变量），绝不进客户端、日志、前端构建产物
- 密钥的
allowedScopes/allowedAgents配置为最小集合——这是委托的第一道闸门 - 有效期按任务给（分钟级），不用上限
- 每个 Agent 用专属密钥，出事只停一把
- 建立密钥使用的审计告警：非预期时段、非预期来源、异常频次
完整硬约束清单与威胁分析见 安全考量。
边界
- 用户不会收到逐次确认，因此你有义务在产品内告知用户"哪些 Agent 在代表你行动"——建议提供"我的授权"页面（见 审计与合规报告）
- 授权依然可撤销、可审计，与路径 A 的产物是同一种委托令牌
- 不适合面向 C 端消费者的知情同意场景
两条路径可以并存
常见的成熟组合：内部工具走路径 B（员工已登录、体验优先），面向客户的功能走路径 A（需要客户本人知情同意）。两者共用同一套 Agent 台账、同一套审计链、同一套吊销手段——切换路径不需要改 Agent 侧代码，只改发起委托时的参数。
常见问题
我们自研的登录系统，不是标准 OIDC，能接吗？ 两个选择：为它加一层标准 OIDC 端点（长期更划算），或先走路径 B（你的服务端已有登录态即可）。
能不能既不换 IdP，也不用管理员预先同意？ 不能。授权必须有人负责——要么用户本人，要么组织。这不是产品限制，是委托语义的要求（见 Consent 与审批）。
多个 Human Identity 提供方能同时接吗？ 架构上按 provider 抽象设计，支持情况见 整合原理。
下一步
- 整合原理：OIDC 与 OAuth Scope 如何打通 —— provider 抽象与支持矩阵。
- Consent 与审批 —— 两条路径背后的授权语义。
- 安全考量 —— 路径 B 的硬约束清单。