1. ## Overview Identity Workload Pool 为智能体、应用和服务提供统一的工作负载身份管理能力。它通过工作负载池划分管理边界，通过工作负载身份表示实际运行的主体，并根据使用场景结合信任锚、工作负载元数据和访问令牌完成身份认证与可信身份传递。本文将现有产品能力集中在一个文档中，帮助您： * 理解各模块的职责及相互关系。 * 查找每项能力对应的 API Action。 * 根据场景选择 AK/SK 或信任锚认证路径。 * 按正确顺序完成配置并获取访问令牌。 * 在智能体调用链中正确理解和使用 TIP Token。本文面向使用 Identity Workload Pool 的产品用户、管理员和集成开发者。API 表中的名称是 API Action 名称；完整请求参数、响应字段和错误码请以对应 API 参考文档为准。 2. ## 核心概念与对应 API 1. ### 工作负载池工作负载池用于集中管理一组相关的智能体、应用或服务身份。不同工作负载池之间可以隔离身份、信任关系和令牌签发范围，适合按照业务、团队、环境或管理边界进行划分。 #### 模块能力 * 按业务或环境建立独立的身份管理边界。 * 管理工作负载池的创建、查询、更新和删除生命周期。 * 在需要信任锚认证时，为池统一绑定或解绑信任锚。 * 隔离不同池中的身份、信任关系和令牌签发范围。 #### API |**能力** |**API Action** | |---|---| |创建工作负载池 |CreateWorkloadPool | |获取工作负载池详情 |GetWorkloadPool | |列出工作负载池 |ListWorkloadPools | |更新工作负载池 |UpdateWorkloadPool | |删除工作负载池 |DeleteWorkloadPool | |绑定工作负载池信任锚 |BindWorkloadPoolTrustAnchor | |解绑工作负载池信任锚 |UnBindWorkloadPoolTrustAnchor | 2. ### 工作负载身份工作负载身份表示实际运行的智能体、应用或服务。访问令牌最终代表的是工作负载池中的一个具体工作负载身份，而不是整个工作负载池。 #### 模块能力 * 为智能体、应用或服务创建独立身份。 * 查询和维护工作负载身份信息。 * 在工作负载停用后清理对应身份。 * 作为访问令牌中工作负载身份信息的主体。 #### API |**能力** |**API Action** | |---|---| |创建工作负载身份 |CreateWorkloadIdentity | |获取工作负载身份详情 |GetWorkloadIdentity | |列出工作负载身份 |ListWorkloadIdentities | |更新工作负载身份 |UpdateWorkloadIdentity | |删除工作负载身份 |DeleteWorkloadIdentity | 3. ### 信任锚（可选）信任锚用于在数据面验证 ECS 身份凭证或外部 Token，并从验证通过的凭证中提取可信身份属性。信任锚定义可信凭证来源，但不直接授予业务资源访问权限。使用 AK/SK 调用访问令牌 API 时，不需要配置信任锚。 #### 模块能力 * 定义可信的外部凭证来源。 * 验证外部 JWT 或火山引擎 ECS 身份凭证。 * 从验证通过的凭证中提取可信身份属性。 * 通过池级绑定控制信任锚的生效范围。 * 使用身份名称模板，根据可信属性确定目标工作负载身份。 #### 支持的典型类型 |**类型** |**验证方式** |**可使用的典型可信属性** | |---|---|---| |token |使用 RSA 公钥验证 JWT，公钥可以使用 PEM 或 Base64 格式 |iss、sub、aud | |volc_ecs |验证火山引擎 ECS 身份凭证及其来源 |AccountId、EcsId | 信任锚的凭证配置与类型有关，不存在适用于所有信任锚类型的统一配置内容。 #### API |**能力** |**API Action** | |---|---| |创建信任锚 |CreateTrustAnchor | |获取信任锚 |GetTrustAnchor | |列出信任锚 |ListTrustAnchors | |更新信任锚 |UpdateTrustAnchor | |删除信任锚 |DeleteTrustAnchor | #### 信任锚校验顺序 1. 确认信任锚已经绑定到目标工作负载池。 2. 根据信任锚类型验证凭证签名、来源或云资源身份。 3. 从验证通过的凭证中提取可信身份属性。 4. 使用请求中的身份名称或身份名称模板确定目标工作负载身份。 5. 如果目标身份配置了工作负载元数据，继续执行元数据校验。 6. 校验通过后签发代表目标工作负载身份的访问令牌。 4. ### 工作负载元数据（可选）工作负载元数据绑定到具体的工作负载身份，用于进一步限制哪些凭证可以使用该身份。元数据解决的是“凭证能否使用这个身份”，而不是“这个身份能够访问哪些资源”。如果工作负载身份没有配置元数据，系统不会增加元数据校验限制。 #### 模块能力 * 限制哪些用户 JWT、外部 Token 或 ECS 实例可以使用指定工作负载身份。 * 使用一个或多个可信属性缩小身份的可使用范围。 * 为同一属性维护多个允许值。 * 按属性或属性值移除不再有效的限制。 #### 固定格式每条元数据由属性名和允许值列表组成： |**项目** |**含义** | |---|---| |Key |需要校验的可信身份属性名称 | |Values |该属性允许使用的一个或多个值，最多 255 个 | 一个 Key 可以包含多个允许值，凭证属性匹配其中任意一个值即可。存在多个参与校验的属性时，每个属性都需要满足各自的允许范围。 |**凭证来源** |**常用属性** | |---|---| |AK/SK 调用中携带的用户 JWT |sub、userpool_id、client_id | |信任锚验证的外部 Token |iss、sub、aud | |信任锚验证的 ECS 身份凭证 |AccountId、EcsId | 自定义属性只有在所选认证路径能够从凭证中提供对应可信属性时，才能形成有效限制。 #### API |**能力** |**API Action** | |---|---| |绑定工作负载元数据 |AddWorkloadMetaData | |解绑工作负载元数据 |RemoveWorkloadMetaData | #### 元数据校验顺序 1. 请求中的身份名称或信任锚的身份名称模板确定目标工作负载身份。 2. 系统从用户 JWT 读取可信属性，或通过信任锚验证外部凭证并提取可信属性。 3. 系统读取目标工作负载身份绑定的元数据。 4. 对每个参与校验的属性，检查凭证值是否匹配允许值列表中的任意值。 5. 所有参与校验的属性均满足条件后，凭证才可以使用该身份继续获取访问令牌。 5. ### 访问令牌与TIP令牌访问令牌用于让通过身份认证的工作负载访问目标服务。令牌可以只代表工作负载身份，也可以根据 API 选择同时携带工作负载与用户身份。 TIP 是 Trust Identity Propagation（可信身份传递）的缩写。TIP Token 不是一种独立格式，而是工作负载访问令牌在智能体调用链中承担的身份传递角色。当上游智能体把自己的访问令牌传递给受信任的下游智能体时，该令牌可作为 TIP Token。下游智能体验证其中的身份信息后，再获取代表自身工作负载身份的新访问令牌，以继续访问服务或调用其他智能体。 #### 模块能力 * 获取只代表工作负载身份的访问令牌。 * 基于已有用户 JWT 获取同时包含工作负载和用户身份的访问令牌。 * 基于用户 ID 获取同时包含工作负载和用户身份的访问令牌。 * 在智能体调用链中将访问令牌作为 TIP Token 传递可信身份。 #### API |**能力** |**API Action** | |---|---| |获取仅代表工作负载身份的访问令牌 |GetWorkloadAccessToken | |基于用户 JWT 获取工作负载与用户身份访问令牌 |GetWorkloadAccessTokenForJWT | |基于用户 ID 获取工作负载与用户身份访问令牌 |GetWorkloadAccessTokenForUserId | #### API 选择 * 目标服务只需要工作负载身份时，使用 GetWorkloadAccessToken。 * 已有用户 JWT，并且需要把用户身份带入工作负载请求时，使用 GetWorkloadAccessTokenForJWT。 * 调用方使用用户 ID 标识用户，并且需要同时携带工作负载与用户身份时，使用 GetWorkloadAccessTokenForUserId。 3. ## 模块关系与职责边界各模块在身份认证流程中的关系如下： 1. **工作负载池**确定身份、信任关系和令牌签发的管理边界。 2. **工作负载身份**确定访问令牌代表的具体智能体、应用或服务。 3. **认证方式**确认调用方身份：可以使用 AK/SK，也可以选择信任锚验证外部凭证。 4. **工作负载元数据**在配置后进一步检查凭证是否有资格使用目标身份。 5. **访问令牌**在校验通过后签发，并用于访问目标服务或传递可信身份。 6. **目标资源权限**由后续权限策略或目标服务决定，不由信任锚或工作负载元数据直接决定。身份名称负责选择工作负载身份。使用信任锚时，也可以通过身份名称模板，根据验证后的可信属性生成身份名称。工作负载元数据只校验已经确定的目标身份，不会搜索全部身份，也不会在多个身份之间随机选择。 4. ## 使用流程 1. ### 流程一：使用 AK/SK 获取访问令牌这是不依赖信任锚的标准使用路径。 1. **创建工作负载池** 调用 CreateWorkloadPool 建立管理边界。 2. **创建工作负载身份** 调用 CreateWorkloadIdentity，为需要访问目标服务的智能体、应用或服务建立身份。 3. **按需配置工作负载元数据** 如果需要校验用户 JWT 中的可信属性，调用 AddWorkloadMetaData 为目标身份配置允许范围；不需要额外限制时可跳过。 4. **选择访问令牌 API** 根据是否需要用户身份，选择 GetWorkloadAccessToken、GetWorkloadAccessTokenForJWT 或 GetWorkloadAccessTokenForUserId。 5. **使用访问令牌** 将访问令牌提交给目标服务，由目标服务及其权限策略决定是否允许访问。直接使用 AK/SK 调用访问令牌 API 时，不需要为了签发令牌而额外配置信任锚。 2. ### 流程二：使用外部 Token 或 ECS 身份凭证获取访问令牌此路径适用于希望在数据面验证外部工作负载凭证的场景。 1. **创建工作负载池** 调用 CreateWorkloadPool 建立管理边界。 2. **创建工作负载身份** 调用 CreateWorkloadIdentity 创建访问令牌最终代表的目标身份。 3. **创建信任锚** 调用 CreateTrustAnchor，根据凭证来源选择 token 或 volc_ecs 等类型，并配置对应的验证信息。 4. **绑定信任锚到工作负载池** 调用 BindWorkloadPoolTrustAnchor，使信任锚在目标池中生效。 5. **按需配置身份名称模板** 如果需要根据 sub、EcsId 等可信属性确定身份，可以在信任锚中使用身份名称模板；否则由请求明确指定身份名称。 6. **按需配置工作负载元数据** 调用 AddWorkloadMetaData，限制允许使用目标身份的凭证属性；不需要额外限制时可跳过。 7. **提交外部凭证并获取令牌** 系统验证凭证、提取可信属性、确定目标身份并执行可选的元数据校验，随后签发代表该身份的访问令牌。 8. **使用访问令牌** 将令牌提交给目标服务，由目标服务完成后续权限判断。 3. ### 流程三：在智能体调用链中传递 TIP Token 1. 上游智能体完成认证并获取代表自身工作负载身份的访问令牌。 2. 上游智能体把该令牌作为 TIP Token 传递给受信任的下游智能体。 3. 下游智能体验证 TIP Token 中的工作负载身份，以及按场景携带的用户身份和委托关系。 4. 下游智能体使用自身的工作负载身份获取新的访问令牌。 5. 下游智能体使用新令牌访问目标服务，或继续调用其他受信任智能体。 TIP Token 表示上游请求的可信身份上下文。下游智能体仍应使用自己的工作负载身份获取令牌，以保持调用链中每一跳的身份清晰。 5. ## 场景选择指南 |**场景** |**推荐配置或 API** | |---|---| |使用 AK/SK，以工作负载身份访问服务 |创建池和身份，调用 GetWorkloadAccessToken | |使用 AK/SK，同时携带已有用户 JWT |创建池和身份，调用 GetWorkloadAccessTokenForJWT；按需配置元数据 | |使用 AK/SK，通过用户 ID 携带用户身份 |创建池和身份，调用 GetWorkloadAccessTokenForUserId | |使用外部 JWT 证明工作负载身份 |创建并绑定 token 类型信任锚 | |使用火山引擎 ECS 身份凭证 |创建并绑定 volc_ecs 类型信任锚 | |只允许特定主体、账号或实例使用身份 |使用 AddWorkloadMetaData 配置可信属性允许值 | |不再允许某个属性值使用身份 |使用 RemoveWorkloadMetaData 删除相应允许值 | |多个工作负载共用相同外部凭证格式 |使用明确的身份名称模板或更精确的元数据组合 | |智能体之间需要传递可信身份 |将访问令牌作为 TIP Token 传递，下游再获取自身令牌 | 6. ## 常见问题 ### 使用 AK/SK 时必须配置信任锚吗？不需要。信任锚是验证 ECS 身份凭证或外部 Token 的可选认证方式。使用 AK/SK 调用访问令牌 API 时，可以不配置信任锚。 ### 工作负载元数据是必选配置吗？不是。只有需要进一步限制哪些凭证可以使用某个工作负载身份时才需要配置。未配置元数据时，系统不会增加元数据校验限制。 ### 元数据能决定身份可以访问哪些资源吗？不能。元数据只决定凭证是否可以使用目标工作负载身份。身份能够访问哪些资源，由后续权限策略或目标服务决定。 ### 系统会根据元数据自动选择工作负载身份吗？不会。目标身份由请求中的身份名称或信任锚的身份名称模板确定。元数据只校验已经确定的身份。 ### 一个凭证可以符合多个工作负载身份的元数据吗？可以。如果多个身份配置了相同的允许属性，同一凭证可能有资格使用这些身份。应通过明确的身份名称、身份名称模板或更精确的属性组合确定实际使用的身份。 ### TIP Token 和访问令牌是两种不同格式吗？不是。TIP Token 是访问令牌在可信身份传递场景中的角色。令牌直接用于访问服务时是普通访问令牌；传递给下游智能体时可以作为 TIP Token。 ### 访问令牌代表工作负载池还是工作负载身份？访问令牌代表工作负载池中的具体工作负载身份，而不是整个工作负载池。

智能体身份和权限管理平台