# AgentCore 자격 증명과의 On-behalf-of 토큰 교환
<a name="on-behalf-of-token-exchange"></a>

Amazon Bedrock AgentCore Identity는 OBO(On-Behalf-Of) 토큰 교환을 지원하므로 MCP 서버와 같은 에이전트 및 기타 워크로드가 인바운드 사용자 액세스 토큰을 다운스트림 리소스 서버를 대상으로 하는 범위가 지정된 새 액세스 토큰으로 교환할 수 있습니다. 교환은 한 대상에 대해 발급된 토큰을 다른 다운스트림 대상에 대한 토큰으로 직접 변환하므로 에이전트는 추가 동의 흐름을 트리거하지 않고 인증된 사용자를 대신하여 보호된 리소스에 액세스할 수 있습니다. 교환된 토큰은 에이전트의 고유 자격 증명과 원래 호출자의 자격 증명을 모두 전달하여 리소스 서버에 모든 홉에서 세분화된 제로 트러스트 권한 부여를 적용하는 데 필요한 신호를 제공합니다.

## on-behalf-of 토큰 교환 작동 방식
<a name="how-obo-works"></a>

On-behalf-of 토큰 교환은 기존 OAuth 자격 증명 공급자에 내장되어 있습니다. 에이전트가 다운스트림 토큰을 요청하면 AgentCore Identity는 자격 증명 공급자에 이미 저장된 클라이언트 자격 증명과 함께 업스트림 호출자를 나타내는 인바운드 액세스 토큰을 자동으로 가져와 고객의 IdP 또는 OAuth 권한 부여 서버로 토큰 교환 요청을 브로커링합니다. 요청을 제출하고 응답을 구문 분석한 다음 에이전트에게 반환합니다. 에이전트 개발자는 인바운드 토큰을 처리하거나 클라이언트 암호를 직접 관리할 필요가 없습니다. 권한 부여 서버는 요청된 범위를 부여할지 여부와 위임을 허용할지 여부를 포함하여 최종 권한 부여 결정을 내립니다.

AgentCore 자격 증명은 두 가지 확립된 표준 중 하나를 통해 토큰 교환on-behalf-of 구현하는 자격 증명 공급자를 지원합니다. RFC 8693(OAuth 2.0 토큰 교환)에서 자격 증명 공급자는 표준 토큰 교환 권한 부여 유형을 따라 에이전트의 클라이언트 자격 증명과 함께 subject\_token으로 인바운드 토큰을 제출합니다. 대신 일부 자격 증명 공급자는 RFC 7523 §2.1(OAuth 2.0 권한 부여를 위한 JWT 프로필)을 통해 on-behalf-of 구현합니다. 여기서 인바운드 토큰은 다운스트림 액세스 토큰을 얻기 위한 JWT 권한 부여 권한 부여로 표시됩니다. OAuth 자격 증명 공급자를 설정할 때 자격 증명 공급자가 예상하는 모드를 구성합니다. AgentCore 자격 증명은 해당 자격 증명 공급자와의 프로토콜 차이를 처리합니다.

## on-behalf-of 토큰 교환 구성
<a name="obo-configs"></a>

이 기능을 사용하려면 OAuth 2.0 자격 증명 공급자에서 on-behalf-of 토큰 교환 모드를 구성합니다. 사용자 지정 공급자를 사용할 때 구성을 사용자 지정하거나 지원되는 공급자 중 하나를 선택할 수 있습니다.

### 사용자 지정 OAuth2 자격 증명 공급자
<a name="_custom_oauth2_credential_provider"></a>

 AWS 콘솔on-behalf-of 토큰 교환을 구성하려면 [사용자 지정 공급자를 사용하여 OAuth 클라이언트 추가](identity-add-oauth-client-custom.md)를 참조하세요. CLI를 사용하여 구성할 수도 있습니다.

#### CLI 예제: machine-to-machine 토큰을 액터 토큰으로 사용하여 `TOKEN_EXCHANGE` 권한 부여 유형 사용
<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"
        }
      }
    }
  }'
```

### 공급자별 대리 on-behalf-of 토큰 교환 구성
<a name="_provider_specific_on_behalf_of_token_exchange_config"></a>

AgentCore Identity에는 선택한 공급자 out-of-the-box에 대한 즉시 on-behalf-of 토큰 교환 지원이 포함되며, 각 공급자의 공개 설명서에 따라 미리 구성됩니다. 이러한 기본값을 초과하여 프로토콜 수준 설정을 조정하려면 교환 구성을 완전히 제어할 수 있도록 사용자 지정 공급자를 설정합니다.


| 공급자 이름 | 권한 부여 유형 모드 | Note | 관련 설명서 | 
| --- | --- | --- | --- | 
|  `MicrosoftOauth2`  |  `JWT_AUTHORIZATION_GRANT` <br />\* Microsoft의 On-Behalf-Of 흐름은 계층형 서비스 간의 보안 토큰 교환을 용이하게 하기 위해 JWT-베어러 권한 부여 유형을 사용하여 RFC 7523 표준을 기반으로 구축된 독점 위임 패턴입니다. |  `requested_token_use=on_behalf_of`는 재정의되지 않는 한 요청에 자동으로 추가됩니다. |  [Microsoft 자격 증명 플랫폼 및 OAuth 2.0 On-Behalf-Of 흐름](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow)  | 

## on-behalf-of 토큰 교환 사용
<a name="_using_on_behalf_of_token_exchange"></a>

런타임on-behalf-of 토큰을 요청하려면 [GetResourceOauth2Token](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html)을 호출하고 oauth2Flow를 로 설정합니다`ON_BEHALF_OF_TOKEN_EXCHANGE`. [GetWorkloadAccessTokenForJWT](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessTokenForJWT.html)에서 얻은 워크로드 액세스 토큰을 전달합니다.이 토큰은 AgentCore 자격 증명이 교환에서 주체 토큰으로 사용하는 인바운드 토큰을 주체로 포함합니다. 전체 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_type` = `TOKEN_EXCHANGE`
<a name="obo-grant-type-token-exchange"></a>

이 권한 부여 유형을 사용하면 AgentCore 자격 증명은 인바운드 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 />기본값 및 재정의 가능, [customParameters](https://docs.aws.amazon.com/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 자격 증명은 인바운드 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는 먼저 자격 증명 공급자에 대해 [machine-to-machine 인증(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/ko_kr/bedrock-agentcore/latest/devguide/on-behalf-of-token-exchange.html) | 

선택적 `actorTokenScopes` 구성은 클라이언트 자격 증명 요청의 `scope` 파라미터로 사용됩니다.

#### `actor_token_content` = `AWS_IAM_ID_TOKEN_JWT` ( `grant_type` = 인 경우에만 해당`TOKEN_EXCHANGE`)
<a name="obo-actor-token-content-iam-jwt"></a>

AgentCore Identity는 자격 증명 공급자의 토큰 엔드포인트를 aud 클레임으로 [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) 사용하여를 호출한 다음 결과 JWT를 로 전송합니다`actor_token`.


| 파라미터 | 값 | 
| --- | --- | 
|  `actor_token_content`  |  `AWS_IAM_ID_TOKEN_JWT` [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/bedrock-agentcore/latest/devguide/on-behalf-of-token-exchange.html) | 

이 모드에서는 아웃바운드 웹 자격 증명 연동을 위해 계정을 활성화해야 합니다. [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`가 포함되지 않습니다. 클라이언트 인증에서만 액터 자격 증명을 도출하는 자격 증명 공급자와 함께이 모드를 사용합니다.