인바운드 인증 및 아웃바운드 인증으로 인증 및 권한 부여

이 섹션에서는 AgentCore 자격 증명이 있는 OAuth 및 JWT 보유자 토큰을 사용하여 에이전트 런타임에 대한 인증 및 권한 부여를 구현하는 방법을 보여줍니다. Cognito 사용자 풀을 설정하고, JWT 인증을 위한 에이전트 런타임을 구성하고(인바운드 인증), 타사 리소스에 대한 OAuth 기반 액세스(아웃바운드 인증)를 구현하는 방법을 알아봅니다.

전체 예제는 섹션을 참조하세요https://github.com/awslabs/amazon-bedrock-agentcore-samples/.

MCP 서버에서 OAuth를 사용하는 방법에 대한 자세한 내용은 AgentCore 런타임에서 MCP 서버 배포를 참조하세요.

Amazon Bedrock AgentCore 런타임은 호스팅 에이전트를 위한 두 가지 인증 메커니즘을 제공합니다.

게이트웨이에 대한 IAM(SigV4) 인바운드 호출 제한

게이트웨이가 런타임에 대한 단일 관리형 진입점이 되도록 AgentCore 게이트웨이로 AgentCore 런타임을 앞당길 수 있습니다. 이를 통해 정책 기반 권한 부여, Amazon Bedrock Guardrails, 요청 및 응답 인터셉터, 통합 관찰성을 모두 에이전트의 자체 환경 외부에서 적용할 수 있습니다. 전체 근거와 이를 설정하는 방법은 AgentCore Gateway를 사용하여 런타임 전달을 참조하세요.

그러나 이는 호출자가 게이트웨이를 직접 우회하여 런타임에 도달할 수 없는 경우에만 유용합니다. 런타임이 기본 IAM(SigV4) 인바운드 권한 부여를 사용하는 경우 트래픽이 게이트웨이를 통해서만 런타임에 도달하도록 게이트웨이에 대한 호출을 제한할 수 있습니다. 이를 위해 게이트웨이의 실행 역할에 대한 호출을 제한하는 리소스 기반 정책을 런타임에 연결합니다. 게이트웨이는 서비스 역할을 수임하여 런타임에 대한 요청에 서명하므로 게이트웨이 역할은 런타임을 호출하는 보안 주체입니다. 허용 자격 증명 기반 정책이 있더라도 다른 자격 증명이 런타임을 호출할 수 없도록 해당 역할을 허용하고 다른 모든 보안 주체에 Deny 대해 명시적를 추가합니다. 런타임의 리소스 기반 정책에 대한 자세한 내용은 Amazon Bedrock AgentCore의 리소스 기반 정책을 참조하세요.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowOnlyGatewayRole",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
        },
        {
            "Sid": "DenyOtherPrincipals",
            "Effect": "Deny",
            "Principal": { "AWS": "*" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "Condition": {
                "ArnNotEquals": {
                    "aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
                }
            }
        }
    ]
}

JWT 인바운드 권한 부여 및 OAuth 아웃바운드 액세스 샘플

이 안내서에서는 JWT 형식을 사용하여 OAuth 준수 액세스 토큰으로 호출하도록 에이전트 런타임을 설정하는 프로세스를 안내합니다. 샘플 에이전트는 AWS Cognito 액세스 토큰을 사용하여 권한이 부여됩니다. 나중에 에이전트 코드가 사용자를 대신하여 Google 토큰을 가져와 Google Drive를 확인하고 콘텐츠를 가져오는 방법도 알아봅니다.

학습할 내용

이 가이드에서는 다음을 수행하는 방법을 알아봅니다.

사전 조건

시작하기 전에, 다음 사항을 확인해야 합니다.

1단계: 에이전트 프로젝트 생성

agentcore create 명령을 사용하여 선택한 프레임워크로 스켈레톤 에이전트 프로젝트를 설정합니다.

agentcore create

명령을 실행하면 다음과 같은 메시지가 표시됩니다.

다음이 생성됩니다.

2단계: AWS Cognito 사용자 풀 설정 및 사용자 추가

Cognito 사용자 풀을 설정하고 사용자를 생성하려면 프로세스를 자동화하는 셸 스크립트를 사용합니다.

자세한 내용은 2단계: 자격 증명 및 인증 모듈 가져오기를 참조하세요.

Cognito 사용자 풀을 설정하고 사용자를 생성하려면

이 스크립트는 사용자 풀 클라이언트인 Cognito 사용자 풀을 생성하고 사용자를 추가하며 사용자에 대한 보유자 토큰을 생성합니다. 토큰은 기본적으로 60분 동안 유효합니다.

3단계(선택 사항): AgentCore 게이트웨이를 사용하여 런타임 전달

게이트웨이가 런타임에 대한 단일 관리형 진입점이 되도록 AgentCore 게이트웨이로 AgentCore 런타임을 앞당길 수 있습니다. 이를 통해 정책 기반 권한 부여, Amazon Bedrock Guardrails, 요청 및 응답 인터셉터, 통합 관찰성을 모두 에이전트의 자체 환경 외부에서 적용할 수 있습니다. 전체 근거와 이를 설정하는 방법은 AgentCore Gateway를 사용하여 런타임 전달을 참조하세요.

이 런타임을 전달하려면 다음 단계에서 런타임을 배포하기 전에 지금 게이트웨이를 생성합니다. 배포한 후 런타임을 게이트웨이 대상으로 추가합니다.

호출자가 게이트웨이를 우회할 수 없도록 하려면 해당 게이트웨이로부터의 호출만 허용하도록 런타임을 제한합니다. 다음 단계에서 권한 부여자의 일부로를 사용하여 이를 구성합니다allowedWorkloadConfiguration( allowedWorkloadConfiguration: 게이트웨이에 대한 호출 제한 참조).

4단계: 에이전트 배포

{
    "Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
    "Effect": "Allow",
    "Action": "iam:CreateServiceLinkedRole",
    "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
    "Condition": {
        "StringEquals": {
            "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
        }
    }
}

이제 생성한 Cognito 사용자 풀을 사용하여 JWT 권한 부여로 에이전트를 배포합니다. 권한 부여자 구성을 사용하여 에이전트를 생성해야 합니다. 다음 표는 다양한 권한 부여자 구성 파라미터와 이를 사용하여 수신 토큰을 검증하는 방법을 나타냅니다.

client_id와 aud가 모두 제공된 경우 에이전트 런타임 권한 부여자는 둘 다 확인합니다.

allowedWorkloadConfiguration: 게이트웨이에 대한 호출 제한

의 allowedWorkloadConfiguration 필드는 요청의 자격 증명 체인에서 런타임을 호출할 수 있는 워크로드를 customJWTAuthorizer 제한합니다. 자격 증명 체인에 해당 게이트웨이가 포함된 경우에만 런타임이 요청을 수락하도록 허용된 워크로드를 게이트웨이로 설정합니다. 이렇게 하면 OAuth(JWT) 런타임이 3단계에서 설정한 게이트웨이를 통해서만 트래픽이 도착하도록 적용합니다.

다음 필드 중 하나를 사용하여 허용된 워크로드를 제공합니다. 하나 또는 둘 다를 지정할 수 있습니다. 자격 증명 체인이 두 필드의 항목과 일치하면 요청이 수락되므로 둘 다 제공할 필요가 없습니다.

다음 예제에서는 ARN을 기준으로 호출을 특정 AgentCore Gateway로 제한하는 에이전트 런타임을 생성합니다. 게이트웨이를 허용하는 가장 간단한 방법은 hostingEnvironments 단독으로 지정하는 것입니다.

{
    "authorizerConfiguration": {
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
            "allowedClients": ["your-client-id"],
            "allowedWorkloadConfiguration": {
                "hostingEnvironments": [
                    {
                        "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
                    }
                ]
            }
        }
    }
}

또는 워크로드 자격 증명 이름으로 게이트웨이를 식별하거나 두 필드를 모두 지정할 수 있습니다. 둘 다 있는 경우 두 필드의 항목과 일치하는 경우 요청이 허용됩니다. 다음 allowedWorkloadConfiguration 코드 조각은 두 개의 서로 다른 게이트웨이를 허용합니다. 하나는 ARN으로 식별되고 다른 하나는 워크로드 자격 증명 이름으로 식별됩니다.

"allowedWorkloadConfiguration": {
    "hostingEnvironments": [
        {
            "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
        }
    ],
    "workloadIdentities": [
        "my-gateway-2-workload-identity"
    ]
}

에이전트 런타임 생성 및 배포

권한 부여자 구성을 준비한 상태에서 에이전트 런타임을 생성하고 배포합니다. 다음 예제에서는 AgentCore CLI 또는 AWS SDK for Python(Boto3)을 사용하여이 작업을 수행하는 방법을 보여줍니다. 출력의 에이전트 런타임 ARN을 기록해 둡니다. 다음 단계에서 에이전트를 호출하려면이 ARN이 필요합니다.

5단계: 보유자 토큰을 사용하여 에이전트 간접 호출

에이전트가 JWT 권한 부여로 배포되었으므로 이제 보유자 토큰을 사용하여 에이전트를 호출할 수 있습니다.

{
    "Sid": "GetAgentAccessToken",
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
        "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
    ],
    # point to the workload identity for the runtime; the workload identity can be found in
    # the GetAgentRuntime response and has your agent name in it.
    "Resource": [
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
    ]
}

에이전트 호출

Amazon Cognito로 생성한 사용자의 보유자 토큰을 가져옵니다.

# use the password and other details used when you created the cognito user

export TOKEN=$(aws cognito-idp initiate-auth \
    --client-id "$CLIENT_ID" \
    --auth-flow USER_PASSWORD_AUTH \
    --auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
    --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')

다음 지침의 나머지 부분을 사용하여 에이전트를 호출합니다.

OAuth를 사용하여 에이전트를 호출합니다.

OAuth 오류 응답

OAuth로 구성된 에이전트는 RFC 6749(OAuth 2.0) 인증 표준을 따릅니다. 인증이 누락된 경우 서비스는 클라이언트가 GetRuntimeProtectedResourceMetadata API를 통해 권한 부여 서버 엔드포인트를 검색할 수 있도록 (RFC 7235에 따라) WWW-Authenticate 헤더와 함께 401 무단 응답을 반환합니다.

401 무단 - 인증 누락

권한 부여 헤더에 베어러 토큰이 제공되지 않은 경우 응답은 다음과 같습니다.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"

WWW 인증 헤더의 resource_metadata URL은 보호된 리소스 메타데이터(PRM) API를 가리킵니다. PRM API를 사용하면 클라이언트가이 에이전트와 OAuth 엔드포인트 URLs.

6단계: OAuth를 사용하여 도구에 액세스하도록 에이전트 설정

이 섹션에서는 OAuth2 인증을 사용하여 외부 리소스에 안전하게 액세스하기 위해 에이전트 코드를 AgentCore 자격 증명 공급자와 연결하는 방법을 알아봅니다.

다음 예제에서는 에이전트 런타임에서 실행되는 에이전트가 사용자에게 OAuth 동의를 요청하여 Google 계정으로 인증하고 에이전트가 Google Drive 콘텐츠에 액세스할 수 있도록 권한을 부여하는 방법을 보여줍니다.

자격 증명 설정에 대한 자세한 내용은 AgentCore 자격 증명 시작하기를 참조하세요.

6.1단계: 자격 증명 공급자 설정

Google 자격 증명 공급자를 설정하려면 다음을 수행해야 합니다.

호출 역할에 자격 증명 공급자에 액세스하는 데 필요한 권한이 있는지 확인합니다.

6.2단계: 에이전트가 Google Drive 콘텐츠를 읽을 수 있도록 활성화

다음 예제와 같이 에이전트 코어 SDK 주석이 있는 도구를 생성하여 3각 OAuth 프로세스를 자동으로 시작합니다. 에이전트가이 도구를 호출하면 브라우저에서 권한 부여 URL을 열고 에이전트가 Google Drive에 액세스하는 데 동의하라는 메시지가 표시됩니다.

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
    auth_flow="USER_FEDERATION", # 3LO flow
    on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
    print(access_token) #You can see the access_token
    # Make API calls...
    main(access_token)

asyncio.run(read_from_google_drive(access_token=""))

백그라운드에서 일어나는 일

이 코드가 실행되면 다음 프로세스가 발생합니다.

7단계: (선택 사항) AgentCore 런타임에 JWT 토큰 전파

선택적으로 AgentCore 런타임에 권한 부여 헤더를 전달하여 클레임을 추출할 수 있습니다. 요청 헤더 허용 목록 구성을 사용하여이 작업을 수행할 수 있습니다. 자세한 내용은 RequestHeaderConfiguration을 참조하세요.

7.1단계: 헤더를 읽도록 에이전트 코드 수정

이 단계에서는 에이전트 코드를 변경하여 PyJWT 라이브러리를 사용하여 JWT 토큰에서 클레임을 디코딩하고 추출할 수 있습니다.

requirements.txt

생성된 프로젝트의 requirements.txt 파일에 PyJWT 종속성을 추가합니다.

PyJWT

에이전트 코드 업데이트

다음 코드와 같이 생성된 프로젝트(일반적으로 src/main.py 또는 프레임워크 선택에 따라 유사)에서 기본 에이전트 파일을 수정합니다. 인바운드 권한 부여가 완료될 때 AgentCore 런타임에서 이미 검증되었으므로 여기에서 토큰 서명 검증을 건너뛸 수 있습니다.

import jwt
import json
....

@app.entrypoint
def invoke(payload, context):
    auth_header = context.request_headers.get('Authorization')
    if not auth_header:
        return None

    # Remove "Bearer " prefix if present
    token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
    try:
        # Skip signature validation as agent runtime has validated the token already.
        claims = jwt.decode(token, options={"verify_signature": False})
        app.logger.info("Claims: %s", json.dumps(claims))
    except jwt.InvalidTokenError as e:
        app.logger.exception("Invalid JWT token: %s", e)

    .....

7.2단계: 요청 헤더 허용 목록으로 에이전트 생성

AgentCore CLI를 사용하여 요청 헤더 허용 목록으로 에이전트를 구성합니다. 생성된 프로젝트 디렉터리로 이동하여 다음을 실행합니다.

agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none

# Now deploy the agent runtime
agentcore deploy

7.3단계: 에이전트 호출

OAuth를 사용하여 에이전트를 호출하면 CloudWatch Logs의 에이전트 로그에 클레임이 표시됩니다.

문제 해결

토큰 관련 문제를 디버깅하는 방법

토큰 인증에 문제가 발생하면 토큰을 디코딩하여 내용을 검사할 수 있습니다.

echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i<l; i++) printf "="; print "" }' | base64 -D | jq

이렇게 하면 토큰의 페이로드가 출력되며, 이는 다음과 유사합니다.

{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}

토큰 문제를 해결할 때 다음을 확인합니다.