本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 获取工作负载访问令牌
<a name="get-workload-access-token"></a>

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

**Topics**
+ [什么是工作负载访问令牌？](#workload-access-token-overview)
+ [运行时和网关如何自动获取令牌](#how-runtime-gateway-obtain-tokens)
+ [如何手动检索工作负载访问令牌](#manual-token-retrieval-patterns)
+ [`GetWorkloadAccessTokenForUserId`API 的安全控制](#security-controls-getuserid-api)

## 什么是工作负载访问令牌？
<a name="workload-access-token-overview"></a>

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

 **主要特性** 
+  **First-party 仅限服务 ** — 工作负载访问令牌专门用于访问 Amazon 第一方 AgentCore 服务，不能用于外部服务
+  **自动交付 ** — 运行时和网关在执行期间自动将这些令牌提供给代理
+  **安全设计 ** —— Runtime-managed 代理身份无法直接检索工作负载访问令牌，从而防止了令牌提取和滥用
+  **用户和代理身份绑定 **-令牌包含用于安全凭据访问的用户身份和代理身份信息

## 运行时和网关如何自动获取令牌
<a name="how-runtime-gateway-obtain-tokens"></a>

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

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

1. Runtime 从代表用户身份的 OAuth 令牌中提取发行人和子声明

1. 运行时获取代理的关联工作负载标识

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

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

这种自动过程可确保代理无需手动干预即可获得适当范围的令牌。

## 如何手动检索工作负载访问令牌
<a name="manual-token-retrieval-patterns"></a>

根据您识别代理最终用户的方式，可以使用两种模式来检索工作负载访问令牌：

### 模式 1： JWT-based 识别（推荐用于生产）
<a name="token-retrieval-forjwt"></a>

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

 **在以下情况下使用此模式：**
+ 您的应用程序与身份提供商（Cognito、Auth0、Okta 等）集成
+ 你需要最终用户身份的加密证明
+ 您正在部署到生产环境中

### 模式 2： UserId-based 识别
<a name="token-retrieval-foruserid"></a>

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

 **在以下情况下使用此模式：**
+ 您的应用程序管理自己的用户标识符，您需要将客户管理的 UserID 字符串传递给 Identity AgentCore 
+ 您处于 IdP 代币尚不可用的开发或快速启动场景中
+ 您的企业架构在上游解析用户身份，并将可信标识符传递给代理工作负载

 **权衡：**该平台将UserID视为不透明的字符串，无法根据经过身份验证的最终用户身份对其进行验证。安全绑定依赖于调用工作负载传递正确的用户 ID 以及 IAM 策略的适当范围。有关推荐[`GetWorkloadAccessTokenForUserId`API 的安全控制](#security-controls-getuserid-api)的控件，请参见。

### 代码示例
<a name="_code_examples"></a>

以下示例说明了使用这两种方法使用 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”)
```

## `GetWorkloadAccessTokenForUserId`API 的安全控制
<a name="security-controls-getuserid-api"></a>

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

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

该 `GetWorkloadAccessTokenForUserId` API 实施了多项安全控制措施以防止未经授权的访问：
+  **工作负载身份验证 ** — API 验证请求身份是否有权代表指定的工作负载身份执行操作
+  **Service-managed 身份限制 **- Gateway-managed 工作 Runtime-managed 负载身份无法直接检索令牌。这可以防止代理提取令牌以供滥用
+  **IAM 权限要求 ** — 呼叫者必须拥有适当的 IAM 权限`GetWorkloadAccessToken`，包括`GetWorkloadAccessTokenForUserId`、和 `GetWorkloadAccessTokenForJWT` 
+  **令牌范围界定 ** — 令牌的范围限定为特定的用户代理对，确保存储在一个用户下的凭证不能被另一个用户访问
+  **多个身份提供商的用户 ID 分区 ** — 使用多个身份提供商时，使用该模式对用户 ID 进行分区，`provider_id+user_id`以防止用户在不同提供商之间发生冲突。例如，使用`cognito+user123`和`auth0+user123`区分不同身份提供商中具有相同标识符的用户

### 推荐的安全控制措施
<a name="security-controls-getuserid-api-recommendations"></a>

由于平台无法验证 userID 字符串，因此您有责任确保传递给此 API 的值的完整性。应用以下控件：
+  **首选 JWT 可用`GetWorkloadAccessTokenForJWT`时 ** ——该 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 值之间的关系。 Amazon CloudTrail 用于监控`GetWorkloadAccessTokenForUserId`呼叫和检测意外的 userID 值。

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

为了获得额外的安全控制，您可以实施细粒度的访问策略，以限制哪些工作负载身份可以访问特定的凭证提供商。有关更多信息，请参阅[按工作负载身份](scope-credential-provider-access.md)缩小对凭据提供者的访问权限。