View a markdown version of this page

获取工作负载访问令牌 - Amazon Bedrock AgentCore
什么是工作负载访问令牌？运行时和网关如何自动获取令牌如何手动检索工作负载访问令牌GetWorkloadAccessTokenForUserIdAPI 的安全控制

获取工作负载访问令牌

了解什么是工作负载访问令牌、如何获取它们以及使用它们的安全方面对于构建安全代理应用程序至关重要。本节涵盖您需要了解的关键概念和实现模式。

什么是工作负载访问令牌？

工作负载访问令牌是一种经 AWS签名的不透明访问令牌，它使代理能够访问第一方 AgentCore 服务，例如出站凭据提供程序。Runtime 会自动将工作负载访问令牌作为负载标头提供给代理执行实例，从而在大多数情况下无需手动管理令牌。

主要特性

  • First-party 仅限服务 — 工作负载访问令牌专用于访问 AWS 第一方 AgentCore 服务，不能用于外部服务

  • 自动交付 — Runtime 和 Gateway 在执行期间自动向代理提供这些令牌

  • 安全设计 —— Runtime-managed 代理身份无法直接检索工作负载访问令牌，从而防止令牌提取和滥用

  • 用户和代理身份绑定-令牌包含用户身份和代理身份信息，用于安全访问凭证

运行时和网关如何自动获取令牌

当通过 AgentCore Runtime 或 Gateway 通过入站身份验证调用代理时，该服务会自动处理工作负载访问令牌的生成：

  1. 运行时验证入站身份提供商 OAuth 令牌（颁发者、签名）

  2. Runtime 从代表用户身份的 OAuth 令牌中提取颁发者和订阅声明

  3. 运行时获取代理的关联工作负载身份

  4. 同时GetWorkloadAccessTokenForJWT使用用户身份和代理工作负载身份进行运行时调用

  5. Runtime 将工作负载访问令牌作为调用负载标头的一部分传递给代理代码

这种自动过程可确保代理无需人工干预即可接收范围合理的令牌。

如何手动检索工作负载访问令牌

有两种模式可用于检索工作负载访问令牌，具体取决于您如何识别代理的最终用户：

模式 1： JWT-based 识别（建议用于生产）

如果代理的调用方拥有身份提供商为最终用户颁发的 JWT，请使用GetWorkloadAccessTokenForJWT请求工作负载访问令牌。当您提供 JWT 时，Ident AgentCore ity 会验证令牌以确保其签名正确且未过期，并使用其 “iss” 和 “sub” 声明来唯一标识用户。代理代表用户存储的凭证与该经过加密验证的身份相关联，future 的检索需要带有相同身份的有效工作负载访问令牌。

在以下情况下使用此模式：

  • 您的应用程序与身份提供商（Cognito、Auth0、Okta 等）集成

  • 您需要最终用户身份的加密证明

  • 您正在部署到生产环境

模式 2： UserId-based 识别

如果代理的调用方没有识别最终用户的 JWT，请使用GetWorkloadAccessTokenForUserId标识该用户的唯一字符串请求工作负载访问令牌。

在以下情况下使用此模式：

  • 您的应用程序管理自己的用户标识符，您需要将客户管理的 userID 字符串传递给 Identity AgentCore

  • 您正处于 IdP 令牌尚不可用的开发或快速入门场景中

  • 您的企业架构在上游解析用户身份，并将可信标识符传递给代理工作负载

权衡：平台将用户 ID 视为不透明的字符串，无法根据经过身份验证的最终用户身份对其进行验证。安全绑定依赖于调用工作负载传递正确的 userID，以及适当确定范围的 IAM 策略。有关推荐GetWorkloadAccessTokenForUserIdAPI 的安全控制的控件，请参阅。

代码示例

以下示例说明了如何使用 AgentCore SDK 通过以下两种方法检索工作负载访问令牌：

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

GetWorkloadAccessTokenForUserIdAPI 的安全控制

GetWorkloadAccessTokenForUserIdAPI 接受调用者提供的用户标识符字符串，并颁发限于该用户代理对的工作负载访问令牌。此 API 旨在为需要传递客户管理的 userID 字符串的企业客户和开发期间没有身份提供商 (IdP) 令牌可用的构建者提供支持。

重要

当您使用时GetWorkloadAccessTokenForUserId，平台会将该userId值视为不透明的字符串，并且不会根据经过身份验证的最终用户身份对其进行验证。安全绑定完全依赖于调用工作负载传递正确的 userID，以及适当确定您的 IAM 策略的范围。如果您的应用程序可以访问标识最终用户的 JWT，请GetWorkloadAccessTokenForJWT改用，它会在发布工作负载访问令牌之前验证令牌的颁发者、签名和到期时间。

GetWorkloadAccessTokenForUserIdAPI 实施了多种安全控制措施来防止未经授权的访问：

  • 工作负载身份验证 — API 验证请求身份是否有权代表指定的工作负载身份行事

  • Service-managed 身份限制 — Gateway-managed 工作 Runtime-managed 负载身份无法直接检索令牌。这样可以防止代理提取令牌进行滥用

  • IAM 权限要求 — 来电者必须拥有相应的 IAM 权限GetWorkloadAccessToken，包括GetWorkloadAccessTokenForUserId、和 GetWorkloadAccessTokenForJWT

  • 令牌作用域-令牌的作用域仅限于特定的用户代理对，确保存储在一个用户下的凭据无法被另一个用户访问

  • 多个身份提供商的用户 ID 分区-使用多个身份提供商时，请使用该模式对用户 ID 进行分区，provider_id+user_id以防止不同提供商之间的用户冲突。例如，使用cognito+user123和auth0+user123区分不同身份提供商中具有相同标识符的用户

推荐的安全控制措施

由于平台无法验证用户 ID 字符串，因此您有责任确保传递给此 API 的值的完整性。应用以下控件：

  • GetWorkloadAccessTokenForJWT当 JWT 可用时首选 — 该 JWT-based 路径会验证令牌的颁发者和签名，提供用户身份的加密证明。GetWorkloadAccessTokenForUserId仅在 JWT 不可用时使用。

  • 从可信来源派生 userID — userID 值应来自经过身份验证的委托人的上下文（例如，IAM 来电者身份、会话属性或上游身份解析层），而不是接受客户端提供的任意值。这样可以防止经过身份验证的来电者冒充其他用户。

  • 限制 IAM 权限 — 只有受信任的委托人才应拥有该bedrock-agentcore:GetWorkloadAccessTokenForUserId权限。将此权限的范围限定为特定的工作负载身份资源。请勿通过托管策略或通配符资源声明进行广泛授权。

  • 在@@ 不需要GetWorkloadAccessTokenForUserId的地方拒绝 — 对于始终有 JWT 可用的工作负载，请在 IAM 策略中明确拒绝该操作以防止使用 userID 路径：

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • 实施审计日志-记录经过身份验证的 IAM 委托人与正在传递的 userID 值之间的关系。 AWS CloudTrail 用于监控GetWorkloadAccessTokenForUserId呼叫和检测意外的用户 ID 值。

如果您遇到错误 “WorkloadIdentity 已链接到服务，调用者无法检索访问令牌”，则表示工作负载身份由 Runtime 或 Gateway 管理，无法直接检索令牌。此限制有助于维护安全边界并防止未经授权的令牌访问。

要获得其他安全控制，您可以实施细粒度的访问策略，以限制哪些工作负载身份可以访问特定的凭据提供程序。有关更多信息，请参阅按工作负载身份缩小对凭证提供者的访问范围。