게이트웨이 서비스 역할을 사용하여 IAM 기반 아웃바운드 권한 부여 설정 OAuth 클라이언트를 사용하여 아웃바운드 권한 부여 설정 API 키를 사용하여 아웃바운드 권한 부여 설정

게이트웨이에 대한 아웃바운드 권한 부여 설정

아웃바운드 권한 부여를 사용하면 Amazon Bedrock AgentCore 게이트웨이가 인바운드 권한 부여 중에 인증되고 권한이 부여된 사용자를 대신하여 게이트웨이 대상에 안전하게 액세스할 수 있습니다.

AgentCore Gateway는 다음과 같은 유형의 아웃바운드 권한 부여를 지원합니다.

권한 부여 없음(권장되지 않음) - 일부 대상 유형은 아웃바운드 권한 부여를 우회할 수 있는 옵션을 제공합니다. 이 덜 안전한 옵션은 권장되지 않습니다.
IAM 기반 아웃바운드 권한 부여 - 게이트웨이 서비스 역할을 사용하여 AWS 서명 버전 4(Sig V4)로 게이트웨이 대상에 대한 액세스를 인증합니다.
발신자 IAM 자격 증명 - 게이트웨이는 발신자의 IAM 자격 증명을 사용하여 대상에 대한 요청에 서명합니다. 게이트웨이는 연합 액세스 서비스(FAS)를 사용하여 호출자를 대신하여 역할을 수임하고 호출자의 자격 증명으로 아웃바운드 요청에 서명합니다. 이는 대상 서비스가 게이트웨이 서비스 역할이 아닌 원래 호출자의 자격 증명을 기반으로 권한을 부여해야 하는 경우에 유용합니다.
OAuth - 클라이언트 애플리케이션이 리소스에 액세스할 수 있도록 허용하는 개방형 권한 부여 프레임워크입니다. 기본 제공 자격 증명 공급자 또는 사용자 지정 자격 증명 공급자와 함께 OAuth를 사용할 수 있습니다. 자세한 내용은 OAuth 2.0을 참조하세요. 다음 유형의 OAuth 권한 부여를 사용할 수 있습니다.
- 클라이언트 자격 증명 부여 Machine-to-machine 인증(2 레그 OAuth라고도 함). 클라이언트 애플리케이션은 사용자를 대신하여 액세스하지 않고 애플리케이션을 대신하여 리소스에 액세스합니다.
- 권한 부여 코드 부여 - 사용자 위임 액세스(3 레그 OAuth라고도 함). 사용자는 클라이언트 애플리케이션이 사용자를 대신하여 리소스에 액세스하는 데 동의합니다.
- 토큰 교환 권한 부여(On-behalf-of) - 게이트웨이는 인바운드 사용자의 액세스 토큰을 다운스트림 리소스를 대상으로 하는 범위가 지정된 새 액세스 토큰으로 교환합니다. 교환된 토큰은 사용자의 자격 증명과 에이전트의 자격 증명을 모두 보유하므로 다운스트림 서비스는 추가 동의 흐름을 트리거하지 않고 모든 홉에서 세분화된 권한 부여를 적용할 수 있습니다. 자세한 내용은 토큰 교환On-behalf-of 참조하십시오.
토큰 패스스루 - 게이트웨이는 인바운드 권한 부여 토큰을 수정 없이 대상에 직접 전달합니다. 대상 서비스는 토큰을 검증할 책임이 있습니다. 이렇게 하려면 토큰이 검증되었지만 전달을 위해 보존되도록 게이트웨이가 AUTHENTICATE_ONLY 인바운드 권한 부여를 사용해야 합니다.
API 키 - AgentCore 서비스를 사용하여 게이트웨이 대상에 대한 액세스를 인증하는 API 키를 생성합니다.

설정할 수 있는 아웃바운드 권한 부여 유형은 액세스를 허용하는 게이트웨이 대상 유형에 따라 다릅니다.

대상 유형	권한 부여 없음	게이트웨이 서비스 역할	호출자 IAM 자격 증명	OAuth(클라이언트 자격 증명)	OAuth(권한 부여 코드)	OAuth(토큰 교환)	토큰 패스스루	API 키
API 게이트웨이 스테이지	예	예	아니요	아니요	아니요	아니요	아니요	예
Lambda 함수	아니요	예	아니요	아니요	아니요	아니요	아니요	아니요
MCP 서버	예	예	아니요	예	예	예	아니요	예
OpenAPI 스키마	예	예	아니요	예	예	예	아니요	예
Smithy 스키마	아니요	예	아니요	예	아니요	아니요	아니요	아니요
AgentCore 런타임(HTTP)	아니요	예	예	예	아니요	아니요	예	아니요

참고

통합 공급자 템플릿을 대상으로 사용하는 경우 통합 공급자의 기본 제공 템플릿에서 다양한 템플릿에 대해 지원되는 권한 부여 유형을 대상으로 검토합니다.

게이트웨이에 대상을 추가하기 전에 지원되는 방법 중 하나를 통해 대상에 대한 권한 부여를 설정해야 합니다.

참고

AWS Management Console 또는 AgentCore CLI를 사용하여 게이트웨이를 생성하려는 경우이 사전 조건을 건너뛸 수 있습니다. 이러한 도구 중 하나를 사용하는 경우 AgentCore가 대상에 액세스하는 데 필요한 권한을 가진 서비스 역할을 자동으로 생성하도록 할 수 있습니다. 대상을 추가할 때마다 필요한 권한이 서비스 역할에 자동으로 연결됩니다.

주제를 선택하여 해당 유형의 권한 부여를 설정하는 방법을 알아봅니다.

게이트웨이 서비스 역할을 사용하여 IAM 기반 아웃바운드 권한 부여 설정

IAM 기반 아웃바운드 권한 부여를 사용하면 게이트웨이 서비스 역할의 IAM 자격 증명을 사용하여 AWS 서명 버전 4(Sig V4) 로 권한을 부여할 수 있습니다. 이 옵션을 사용하면 Amazon Bedrock AgentCore 서비스가 게이트웨이 호출자를 대신하여 게이트웨이 대상에 인증할 수 있습니다.

이 옵션을 사용하는 경우 게이트웨이 서비스 역할에 bedrock-agentcore:InvokeGateway 권한이 있는지 확인합니다. 게이트웨이는 호출 중에 인증을 위해 서비스 역할 자격 증명을 사용합니다.

MCP 서버 및 OpenAPI 대상에 대한 추가 구성

MCP 서버 또는 OpenAPI 대상과 함께 IAM 기반 아웃바운드 권한 부여를 사용하는 경우 SigV4 서명을 위한 추가 구성을 제공해야 합니다. 에 다음 필드가 iamCredentialProvider 있는 credentialProviderConfigurations를 포함합니다.

서비스(필수) - SigV4 서명에 사용되는 AWS 서비스 이름입니다. 예를 들어 Amazon Bedrock AgentCore에서 호스팅되는 MCP 서버의 bedrock-agentcore 경우
region(선택 사항) - SigV4 서명을 위한 AWS 리전입니다. 리전을 지정하지 않으면 게이트웨이는 자체 리전을 사용합니다.

Lambda, API Gateway 및 Smithy 대상의 경우 iamCredentialProvider 필드를 포함하지 마십시오. 이러한 대상 유형은의 기본 GATEWAY_IAM_ROLE 구성만 지원합니다credentialProviderType. 자격 증명 공급자 구성을 지정하는 방법에 대한 자세한 내용은 AgentCore Gateway 서비스 역할(IAM) 권한 부여를 참조하세요.

IAM 기반 아웃바운드 권한 부여의 보안 모범 사례

게이트웨이 실행 역할은 로 구성된 모든 대상에서 공유됩니다GATEWAY_IAM_ROLE. 권한은 권한 있는 호출자가 게이트웨이를 통해 행사할 수 있는 권한의 상한입니다. 노출을 제한하려면 다음 모범 사례를 따르세요.

실행 역할의 범위를 최소 권한으로 지정 - 구성된 모든 대상에 필요한 권한만 부여합니다. 브로드카드Action나 Resource 와일드카드를 사용하지 마세요.
서로 다른 신뢰 경계에 대해 별도의 게이트웨이 사용 - 대상의 민감도 수준이 다르거나 워크로드가 다른 경우 별도의 실행 역할이 있는 별도의 게이트웨이 뒤에 배포합니다.
정책 엔진을 사용하여 호출자 액세스 제한 - 공유 게이트웨이에서 정책 엔진을 사용하여 호출할 수 있는 호출자를 제어하여 단일 호출자 권한의 블래스트 반경을 제한합니다.

OAuth 클라이언트를 사용하여 아웃바운드 권한 부여 설정

OAuth 클라이언트를 사용하여 아웃바운드 권한 부여를 설정하려면 AgentCore 자격 증명 서비스를 사용하고 기본 제공 자격 증명 공급자에서 클라이언트를 생성하여 받는 클라이언트 자격 증명을 지정합니다(공급자 설정 및 구성 또는 사용자 지정 자격 증명 공급자 참조.

OAuth 클라이언트를 사용하여 아웃바운드 권한 부여를 설정하려면

지원되는 타사 공급자에 클라이언트 애플리케이션을 등록합니다.
아웃바운드 권한 부여를 설정할 때 참조할 클라이언트 ID, 클라이언트 보안 암호 및 기타 값을 받게 됩니다.
요구 사항에 따라 아래 단계 중 하나를 따릅니다.
- 내장 자격 증명 공급자를 사용하여 콘솔에서 아웃바운드 권한 부여를 구성하려면 포함된 공급자를 사용하여 OAuth 클라이언트 추가의 단계를 따릅니다.
- 사용자 지정 자격 증명 공급자를 사용하여 콘솔에서 아웃바운드 권한 부여를 구성하려면 사용자 지정 공급자를 사용하여 OAuth 클라이언트 추가의 단계를 따릅니다.
- API를 사용하여 아웃바운드 권한 부여를 구성하려면 AgentCore 컨트롤 플레인 엔드포인트 중 하나와 함께 CreateOauth2CredentialProvider를 전송합니다. 예제는 OAuth 클라이언트 권한 부여 설정 예제를 참조하세요.
  
  참고
  oauth2ProviderConfigInput 필드가 매핑되는 JSON 객체의 모양은 사용하는 공급자에 따라 달라지며 지정한 credentialProviderVendor 값과 일치해야 합니다. 다양한 자격 증명 공급자에 대한 다양한 구성의 예를 보려면 공급자 설정 및 구성에서 선택한 자격 증명 공급자의 아웃바운드 권한 부여 예제를 참조하세요.
생성된 자격 증명 ARN( APIcredentialProviderArn의 )과 AWS Secrets Manager 보안 암호 ARN( API의 )secretArn을 기록해 둡니다. 게이트웨이 대상을 생성할 때 이러한 값을 사용합니다.

(사용자 지정 게이트웨이 서비스 역할을 사용하는 경우) 게이트웨이 서비스 역할에 다음 자격 증명 기반 정책을 연결합니다.


{
"Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "GetWorkloadAccessToken",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetWorkloadAccessToken",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
        ]
      },
      {
        "Sid": "GetResourceOauth2Token",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetResourceOauth2Token",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/oauth2credentialprovider/CredentialName"
        ]
      },
      {
        "Sid": "GetSecretValue",
        "Effect": "Allow",
        "Action": [
            "secretsmanager:GetSecretValue",
        ],
        "Resource": [
            "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
        ]
      }
    ]
}

다음 필드의 값을 바꿉니다.

GetWorkloadAccessToken 문에서 Resource 목록의 GatewayName을 게이트웨이 이름으로 바꿉니다.
GetResourceOauth2Token 문에서 Resource 목록의 값을 방금 생성한 자격 증명의 ARN으로 바꿉니다.
GetSecretValue 문에서 Resource 목록의 값을 자격 증명을 생성할 때 응답에 반환된 AWS 보안 암호의 ARN으로 바꿉니다.

OAuth 클라이언트 권한 부여 설정 예제

다음 예제에서는 게이트웨이 대상에 대해 OAuth 클라이언트를 통해 권한 부여를 설정하는 방법을 보여줍니다.

예

API 키를 사용하여 아웃바운드 권한 부여 설정

API 키를 사용하여 아웃바운드 권한 부여를 설정하려면 AgentCore 자격 증명 서비스를 사용하고 지원되는 자격 증명 공급자로부터 받는 API 키를 지정합니다.

OAuth 클라이언트를 사용하여 아웃바운드 권한 부여를 설정하려면

지원되는 타사 공급자에 클라이언트 애플리케이션을 등록합니다.
공급자의 서비스에 대한 API 키를 설정합니다. 게이트웨이 대상을 추가할 때 지정할 다음 값을 기록해 둡니다.
- 자격 증명 위치 - API 키를 헤더에 배치해야 하는지 아니면 쿼리 파라미터로 배치해야 하는지 여부입니다.
- 자격 증명 접두사 - 자격 증명의 접두사(예: 베어러).
요구 사항에 따라 아래 단계 중 하나를 따릅니다.
- AgentCore 콘솔에서 API 키를 생성하려면 API 키 추가의 단계를 따르고 API 키의 값을 지정합니다.
- AgentCore API를 사용하여 API 키를 생성하려면 AgentCore 컨트롤 플레인 엔드포인트 중 하나를 사용하여 CreateApiKeyCredentialProvider 요청을 보내고 apiKey 필드에 API 키 값을 지정합니다. 예제는 API 키 설정 예제를 참조하세요.
게이트웨이 대상을 추가할 때 지정할 다음 값을 기록해 둡니다.
- 자격 증명 공급자 ARN - 자격 증명 공급자에 대해 생성된 Amazon 리소스 이름(ARN)입니다.
- 이름 - API 키에 지정한 이름입니다.
- 보안 암호 ARN - API 키에 대해 생성된 AWS Secrets Manager 보안 암호 ARN입니다.

(사용자 지정 게이트웨이 서비스 역할을 사용하는 경우) 게이트웨이 서비스 역할에 다음 자격 증명 기반 정책을 연결합니다.


{
"Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "GetWorkloadAccessToken",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetWorkloadAccessToken",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
        ]
      },
      {
        "Sid": "GetResourceApiKey",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetResourceApiKey",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/apikeycredentialprovider/Name"
        ]
      },
      {
        "Sid": "GetSecretValue",
        "Effect": "Allow",
        "Action": [
            "secretsmanager:GetSecretValue",
        ],
        "Resource": [
            "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
        ]
      }
    ]
}

다음 필드의 값을 바꿉니다.

GetWorkloadAccessToken 문에서 Resource 목록의 GatewayName을 게이트웨이 이름으로 바꿉니다.
GetResourceApiKey 문에서 Resource 목록의 값을 방금 생성한 자격 증명의 ARN으로 바꿉니다.
GetSecretValue 문에서 Resource 목록의 값을 자격 증명을 생성할 때 응답에 반환된 AWS 보안 암호의 ARN으로 바꿉니다.

API 키 설정 예제

다음 예제에서는 게이트웨이 대상에 대한 API 키를 설정하는 방법을 보여줍니다.

예

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

인바운드 권한 부여 설정

게이트웨이 설정