智能体身份和权限管理平台
智能体身份和权限管理平台
文档指南
请输入
- 文档首页
智能体身份和权限管理平台用户指南身份管理Agent Identity Token 格式定义
复制全文
下载 pdfAgent Identity Token 格式定义
文档反馈
问问助手背景
本文档定义了火山 Agent Identity 服务签发的两类 Token 格式与字段规范。两类令牌池分别面向不同的身份主体：
设计原则：标准兼容（符合 OIDC/JWT 规范）、可扩展（支持自定义 Claims 和 Agent 链路）、安全优先（完整的校验与审计机制）。
UserPool 和 WorkloadPool 的 Token 都符合 OIDC 规范，校验逻辑一致，详见本文"OIDC Token 校验逻辑"章节。
UserPool Token
UserPool Token 是面向终端用户的身份令牌，通过联邦登录从外部 IDP（如 Feishu、Dingding）获取用户身份信息后签发。
完整示例（Feishu 联邦登录）
完整示例（Dingding 联邦登录）
标准 JWT 字段
特殊字段说明
除标准 Claim 字段外，UserPool Token 额外支持以下字段：
最佳实践
- 使用 sub 作为 UserPool 用户的稳定唯一标识；业务库里不要用邮箱、手机号、用户名做主键关联，因为这些字段可能变更或不唯一。
- 上游 IdP 用户标识只依赖 external.claims.external_provider_user_identifier；不要依赖 external.claims.sub、open_id、union_id 等 provider 特定字段，除非业务明确绑定某个 provider。
- 如果业务需要使用外部身份提供商返回的其他字段，请先定义自定义属性并配置 IDP 属性映射，再使用 token 中对应的自定义属性。external.claims 的内容受外部 Claims Propagation 配置影响，可能因 minimum、full 或 custom 策略而变化。因此，不建议将其中的其他外部 claim 作为稳定契约依赖。
- 组/部门授权优先使用 UID 类字段：identity_userpool_group_uids、identity_userpool_department_ids。
Feishu external.claims 字段说明
Email、enterprise_email、mobile、tenant_key、employee_no、user_id 字段依赖于飞书应用权限和 auth 请求的 scopes 配置。除了 external_provider_user_identifier 字段，不建议将使用其他的任何 external.claims 字段作为稳定契约依赖
Dingding external.claims 字段说明
Mobile、email 字段依赖于钉钉应用权限和请求的 scopes 配置。除了 external_provider_user_identifier 字段，不建议将使用其他的任何 external.claims 字段作为稳定契约依赖
Agent Token / Agent TIP Token
Agent Token 面向工作负载（服务/Agent），支持通过 act 字段记录 Agent 执行链路，实现 A2A 多层级调用场景的身份追踪。
完整示例
标准 JWT 字段
特殊字段说明
除标准 Claim 字段外，Agent Token 额外支持以下字段：
Agent Delegation Chain( act)
act 字段是 Agent Token 的核心扩展，用于记录 Agent 的执行委托链。采用嵌套结构，最外层的 sub 表示最近执行的 Agent。
数据结构定义：
语义说明：
上面的例子表示：用户 test_user 发起调用，执行路径经过智能体 test_agent_1 到智能体 test_agent_2。
调用链路解读：
act 字段的嵌套规则： act 最外层的 sub 表示最近（最后）执行的 Agent，嵌套越深表示越早参与调用链的 Agent。调用链的起始发起者始终通过 Token 顶层的 sub 字段标识。
如果没有 act 字段，说明当前 Agent Token 仅代表 Agent 身份，顶层的 sub 字段标识该 Agent 信息。
OIDC Token 校验逻辑
UserPool 和 WorkloadPool 的 Token 都符合 OIDC 规范，校验流程一致。
步骤 1：基础格式合法性校验（前置过滤）
先排除明显无效的 Token，避免后续无意义计算：
- 格式校验：
- ID Token 必须是 JWT 格式（三段式：header.payload.signature，用 . 分隔）
- 每一段必须是 Base64URL 编码（区别于普通 Base64，无 +///= 特殊字符）
- 解码 payload 后必须是合法 JSON（无语法错误）
- 空值/篡改校验：
- 拒绝空 Token、长度异常的 Token（如过短/过长）
- 拒绝被篡改的格式（如多/少 . 分隔符）
步骤 2：签名校验（核心防篡改）
OIDC 最核心的校验步骤，确保 Token 由可信的授权服务器（AS） 签发，且未被篡改：
2.1 确定签名算法（从 Header 提取）
解码 ID Token 的 header 部分，提取 alg 字段（签名算法），常用算法：
- RS256：非对称加密，用公钥验签（私钥仅 AS 持有，最安全）— Agent Identity 使用此算法
- HS256：对称加密，用共享密钥验签（仅适合信任边界内的场景）
禁止使用 none（无签名），属于高危漏洞。
2.2 获取验签密钥（核心前提）
必须从 AS 的 OIDC 发现端点（/.well-known/openid-configuration）获取公钥/密钥：
- 访问 AS 的发现端点（如 https://auth.example.com/.well-known/openid-configuration）
- 提取 jwks_uri 字段（如 https://auth.example.com/jwks）
- 从 jwks_uri 获取 JSON Web Key Set（JWKS），包含验签用的公钥
- 根据 header 中的 kid 字段确定对应的公钥
2.3 执行签名校验
用获取的公钥/密钥，结合 alg 算法，验证 Token 的签名是否合法。原理：AS 用私钥/共享密钥签名 Token，依赖方（RP）用公钥/共享密钥验签，验签失败则 Token 被篡改，直接拒绝。
步骤 3：Token Claim 校验
在这个步骤提取核心需要用的自定义字段。必选校验项 + 推荐校验项 如下：
步骤 4：上下文一致性校验（防重放/越权）
即使 Token 本身合法，也需校验"使用上下文"是否匹配：
- Nonce 校验（核心防重放）：授权请求时 RP 生成随机 nonce 传给 AS，AS 将 nonce 写入 ID Token；校验时确保一致（用完即删）
- 客户端身份校验：若 Token 包含 azp（授权方），需验证 azp 是合法的 Client ID
- 认证方法校验（amr）：若 RP 要求特定认证方式（如 MFA），需验证 amr 包含预期值
- 会话一致性：结合 sid（会话 ID），验证 Token 所属会话未被撤销
步骤 5：Access Token 额外校验
若用 Access Token 访问资源，还需补充：
- 格式校验：JWT 格式需验签 + Claim 校验；随机字符串需调用 AS 的 Introspection 端点验证
- 权限范围校验：验证 scope 包含访问资源所需的权限（如 openid email profile）
- 关联校验：通过 at_hash 验证 Access Token 与 ID Token 属于同一授权流程
附录：标准 Claim 字段参考
核心标准 Claim 字段（按使用频率排序）
所有标准字段均为小写（规范约定），时间类字段均为 Unix 时间戳（秒级）。
重点总结
- 核心标准字段：exp（必用）、iat、iss 是最常用的三个，覆盖"过期、签发、来源"核心验证
- 安全关键：exp 控制过期，jti 防重放，aud 防越权，按需组合使用
- 格式要点：时间字段用秒级 Unix 戳，标准字段小写，避免和自定义字段冲突
示例：包含标准 Claim 的 JWT Payload
验证逻辑顺序
接收方解析 JWT 时，建议按以下顺序验证：
- nbf（若有）：当前时间 ≥ nbf
- exp（若有）：当前时间 < exp
- iss/aud（若有）：匹配预期的签发者/受众
- 最后验证签名，再使用 sub/act 等字段
最近更新时间：2026.07.13 16:31:10
这个页面对您有帮助吗？
有用
有用
无用
无用