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

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

## 代币交换的工作原理
<a name="how-obo-works"></a>

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

AgentCore Identity 支持通过两个既定标准中的任何一个实现代币交换的身份提供商。在 RFC 8693（OAuth 2.0 令牌交换）下，凭证提供者遵循标准的代币交换授予类型，将入站令牌作为主体\_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>

要在 AWS 控制台上为自定义提供商配置代币交换，请参阅使用自定义提供商[添加 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_GRAN` T 授权类型
<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 />\* Microsoft 的 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.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html)w 并将其设置为。`ON_BEHALF_OF_TOKEN_EXCHANGE`传递您从中获得的工作负载访问令牌 [GetWorkloadAccessTokenForJWT](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessTokenForJWT.html)——此令牌将入站令牌作为主体，Ident AgentCore ity 将其用作交换中的主题令牌。如需完整的 API 参考，请参阅 AWS 文档。

```
# 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_typ` `e = 代币交换`
<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.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html#API_GetResourceOauth2Token_RequestSyntax)  | 

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

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


| 参数 | 值 | 
| --- | --- | 
|  `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` [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/bedrock-agentcore/latest/devguide/on-behalf-of-token-exchange.html) | 

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

#### `actor_token_content = _TOKEN_JWT（仅当 grant_typ` `e = AWS_IAM_IDTOKEN_EXCHANGE 时）`
<a name="obo-actor-token-content-iam-jwt"></a>

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


| 参数 | 值 | 
| --- | --- | 
|  `actor_token_content`  |  `AWS_IAM_ID_TOKEN_JWT` [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/bedrock-agentcore/latest/devguide/on-behalf-of-token-exchange.html) | 

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

#### `actor_token_content = NONE（仅当 grant_type = TOKEN` `_EXCHANGE 时）`
<a name="obo-actor-token-content-none"></a>

代币交换请求中不包含`actor_token`或`actor_token_type`。将此模式与仅通过客户端身份验证派生参与者身份的身份提供者一起使用。