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

# On-behalf-of 使用 AgentCore 身份进行代币交换
<a name="on-behalf-of-token-exchange"></a>

Amazon Bedrock I AgentCore dentity 支持 On-Behalf-Of (OBO) 代币交换，使代理和其他工作负载（例如 MCP 服务器）能够将入站用户访问令牌交换为针对下游资源服务器的新范围访问令牌。当交易所将为一个受众发放的代币直接转换为针对其他下游受众的代币时，您的代理可以代表经过身份验证的用户访问受保护的资源，而无需触发额外的同意流程。交换的代币既带有代理自己的身份，也带有原始调用者的身份，为资源服务器提供了在每跳执行精细的零信任授权所需的信号。

## 代币交易是如何运作的
<a name="how-obo-works"></a>

On-behalf-of 代币交换内置于现有的 OAuth 凭证提供商中。当代理请求下游令牌时，I AgentCore dentity 会自动获取代表上游呼叫者的入站访问令牌以及已存储在凭证提供商中的客户证书，并将代币交换请求代理给客户的 IdP 或 OAuth 授权服务器。它提交请求，解析响应并将其返回给代理。代理开发人员无需处理入站令牌或直接管理客户端密钥。授权服务器做出最终授权决定，包括是否授予所请求的范围以及是否允许委托。

AgentCore Identity 支持身份提供商通过两种既定标准中的任何一种实施代币交换。根据RFC 8693（OAuth 2.0代币交换），凭证提供者遵循标准的代币交换授权类型，将入站令牌作为subject\_token与代理的客户凭证一起提交。一些身份提供商改为通过 RFC 7523 第 2.1 节（OAuth 2.0 授权拨款的 JWT 配置文件）来代其实现，其中，入站令牌以 JWT 授权的形式呈现，用于获取下游访问令牌。在设置 OAuth 凭据提供商时，您可以配置身份提供商期望的模式；Ident AgentCore ity 负责处理与那里的协议差异。

## 代表代币交易配置代币交换
<a name="obo-configs"></a>

要使用此功能，请在您的 OAuth 2.0 凭证提供商上配置代币交换模式。在使用自定义提供商时，您可以自定义配置，也可以从支持的提供商中进行选择。

### 自定义 OAuth2 凭证提供商
<a name="_custom_oauth2_credential_provider"></a>

要在 Amazon 控制台上为自定义提供商配置代币交换，请参阅使用自定义提供商[添加 OAuth 客户端。](identity-add-oauth-client-custom.md)您也可以使用 CLI 对其进行配置

#### CLI 示例：使用 `TOKEN_EXCHAN` GE 授权类型和机器间代币作为角色代币
<a name="_cli_example_using_token_exchange_grant_type_with_machine_to_machine_token_as_actor_token"></a>

```
aws bedrock-agentcore-control create-oauth2-credential-provider \
  --cli-input-json '{
    "name": "sample-obo-custom",
    "credentialProviderVendor": "CustomOauth2",
    "oauth2ProviderConfigInput": {
      "customOauth2ProviderConfig": {
        "oauthDiscovery": {
          "discoveryUrl": "https://my.idp.com/.well-known/openid-configuration"
        },
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "clientAuthenticationMethod": "CLIENT_SECRET_BASIC",
        "onBehalfOfTokenExchangeConfig": {
          "grantType": "TOKEN_EXCHANGE",
          "tokenExchangeGrantTypeConfig": {
            "actorTokenContent": "M2M",
            "actorTokenScopes": ["scope1", "scope2"]
          }
        }
      }
    }
  }'
```

#### CLI 示例：使用 `JWT_AUTHORIZATION_GRANT 授权类型`
<a name="_cli_example_using_jwt_authorization_grant_grant_type"></a>

```
aws bedrock-agentcore-control create-oauth2-credential-provider \
  --cli-input-json '{
    "name": "sample-obo-custom",
    "credentialProviderVendor": "CustomOauth2",
    "oauth2ProviderConfigInput": {
      "customOauth2ProviderConfig": {
        "oauthDiscovery": {
          "discoveryUrl": "https://my.idp.com/.well-known/openid-configuration"
        },
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "clientAuthenticationMethod": "CLIENT_SECRET_BASIC",
        "onBehalfOfTokenExchangeConfig": {
          "grantType": "JWT_AUTHORIZATION_GRANT"
        }
      }
    }
  }'
```

### 提供商特定的代币交换配置
<a name="_provider_specific_on_behalf_of_token_exchange_config"></a>

AgentCore 身份包括对选定提供商的开箱即用的代币交换支持，这些支持根据每个提供商的公开文档进行了预先配置。要在这些默认值之外调整协议级别设置，请设置自定义提供商以完全控制交换配置。


| 提供商名称 | 拨款类型模式 | 备注 | 相关文档 | 
| --- | --- | --- | --- | 
|  `MicrosoftOauth2`  |  `JWT_AUTHORIZATION_GRANT` <br />\* 微软的 On-Behalf-Of 流程是建立在 RFC 7523 标准之上的专有委托模式，使用 JWT-bearer 授权类型来促进分层服务之间的安全令牌交换。 |  `requested_token_use=on_behalf_of`除非被覆盖，否则会自动添加到请求中。 |  [微软身份平台和 OAuth 2.0 流程 On-Behalf-Of ](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow)  | 

## 使用代币交换
<a name="_using_on_behalf_of_token_exchange"></a>

要在运行时代表代币请求令牌，请调用 OAuth2Flo [ GetResourceOauth2Token ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html) w 并将其设置为。`ON_BEHALF_OF_TOKEN_EXCHANGE`传递您从中获得的工作负载访问令牌 [ GetWorkloadAccessTokenForJWT ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessTokenForJWT.html) ——该令牌以入站令牌作为主题，I AgentCore dentity 在交易所中使用该令牌作为主题令牌。有关完整的 API 参考，请参阅 Amazon 文档。

```
# obtain workload access token using inbound token
aws bedrock-agentcore get-workload-access-token-for-jwt --workload-name sample-workload \
      --user-token "inbound-jwt-token"

{
    "workloadAccessToken": "workload-access-token"
}

# perform on-behalf-of token exchange
aws bedrock-agentcore get-resource-oauth2-token --resource-credential-provider-name sample-obo-provider \
      --oauth2-flow ON_BEHALF_OF_TOKEN_EXCHANGE --scopes "sample-scope" \
      --workload-identity-token "workload-access-token"

{
    "accessToken": "on-behalf-of-token"
}
```

## 授权类型和代币类型
<a name="obo-grant-type-and-token-types"></a>

### `grant_type = 代币交换` ``
<a name="obo-grant-type-token-exchange"></a>

使用这种授权类型， AgentCore Identity 会将入站 JWT 作为主题令牌发送以获取访问令牌。将`actor_token_content`值配置为`M2M``AWS_IAM_ID_TOKEN_JWT`、或之一 `NONE` 


| 参数 | 值 | 
| --- | --- | 
|  `grant_type`  |  `TOKEN_EXCHANGE`（我们在构造代币交换请求`urn:ietf:params:oauth:grant-type:token-exchange`时将其映射到） | 
|  `subject_token`  | 在构造代币交换请求`urn:ietf:params:oauth:token-type:jwt`时，我们使用入站 JWT 令牌并将主题令牌类型映射到。<br />默认，可以覆盖，参见自定义参数 [https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html#API_GetResourceOauth2Token_RequestSyntax](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html#API_GetResourceOauth2Token_RequestSyntax)  | 

### `grant_type = JWT_AUTHORIZATION_` GRANT ``
<a name="obo-grant-type-jwt-auth-grant"></a>

使用这种授权类型， AgentCore Identity 会发送入站 JWT 作为获取访问令牌的授权。无需`actor_token_content`配置，因为此授权类型不需要任何 Actor 代币。


| 参数 | 值 | 
| --- | --- | 
|  `grant_type`  |  `JWT_AUTHORIZATION_GRANT`（我们在构造代币交换请求`urn:ietf:params:oauth:grant-type:jwt-bearer`时将其映射到） | 
|  `assertion`  | 入站 JWT 代币 | 

#### `actor_token_content` = `M2M`（仅当 grant\_type = TOKEN\_EXCHANGE 时）````
<a name="obo-actor-token-content-m2m"></a>

AgentCore Identity 首先[对凭据提供商执行机器对机器身份验证（授予 OAuth 2.0 客户端凭证）](common-use-cases.md#machine-to-machine-auth)以获取访问令牌，然后将其作为。`actor_token`


| 参数 | 值 | 
| --- | --- | 
|  `actor_token_content`  |  `M2M` +  我们在构造代币交换请求`urn:ietf:params:oauth:token-type:access_token`时将其映射到 <br />+  我们通过`client_credentials`授予获得访问令牌  | 

可选`actorTokenScopes`配置用作客户端凭证请求的`scope`参数。

#### `actor_token_content` = \_TOKEN\_JWT（仅当 grant\_type = `AWS_IAM_ID TOKEN_EXCHANGE` 时）````
<a name="obo-actor-token-content-iam-jwt"></a>

AgentCore [`sts:GetWebIdentityToken`](https://docs.amazonaws.cn/STS/latest/APIReference/API_GetWebIdentityToken.html)使用凭证提供商的令牌端点作为 aud 声明进行身份调用，然后将生成的 JWT 作为. `actor_token` 


| 参数 | 值 | 
| --- | --- | 
|  `actor_token_content`  |  `AWS_IAM_ID_TOKEN_JWT` +  我们在构造代币交换请求`urn:ietf:params:oauth:token-type:jwt`时将其映射到 <br />+  我们通过以下方式获得 JWT [`sts:GetWebIdentityToken`](https://docs.amazonaws.cn/STS/latest/APIReference/API_GetWebIdentityToken.html)   | 

此模式要求您的账户启用出站 Web 联合身份验证。请参阅[`iam:EnableOutboundWebIdentityFederation`](https://docs.amazonaws.cn/IAM/latest/APIReference/API_EnableOutboundWebIdentityFederation.html)。

#### `actor_token_content` = `无`（仅当 grant\_type = TOKEN\_EXCHANGE 时）````
<a name="obo-actor-token-content-none"></a>

代币交换请求中没有`actor_token`或`actor_token_type`包含在内。将此模式与身份提供商一起使用，身份提供商仅从客户端身份验证中获取参与者身份。