워크로드 액세스 토큰 가져오기
워크로드 액세스 토큰이 무엇인지, 토큰을 얻는 방법, 토큰 작업의 보안 측면을 이해하는 것은 보안 에이전트 애플리케이션을 구축하는 데 필수적입니다. 이 섹션에서는 알아야 할 주요 개념과 구현 패턴을 다룹니다.
주제
워크로드 액세스 토큰이란 무엇입니까?
워크로드 액세스 토큰은 에이전트가 아웃바운드 자격 증명 공급자와 같은 자사 AgentCore 서비스에 액세스할 수 있도록 AWS하는 서명된 불투명 액세스 토큰입니다. 런타임은 에이전트 실행 인스턴스에 워크로드 액세스 토큰을 페이로드 헤더로 자동으로 제공하므로 대부분의 시나리오에서 수동 토큰 관리가 필요하지 않습니다.
주요 특징
-
자사 서비스만 해당 - 워크로드 액세스 토큰은 AWS 자사 AgentCore 서비스에 액세스하는 전용이며 외부 서비스에 사용할 수 없습니다.
-
자동 전송 - 런타임 및 게이트웨이는 실행 중에 에이전트에게 이러한 토큰을 자동으로 제공합니다.
-
설계별 보안 - 런타임 관리형 에이전트 ID는 워크로드 액세스 토큰을 직접 검색할 수 없으므로 토큰 추출 및 오용이 방지됩니다.
-
사용자 및 에이전트 자격 증명 바인딩 - 토큰에는 보안 자격 증명 액세스를 위한 사용자 자격 증명과 에이전트 자격 증명 정보가 모두 포함됩니다.
런타임 및 게이트웨이가 토큰을 자동으로 가져오는 방법
인바운드 인증으로 AgentCore 런타임 또는 게이트웨이를 통해 에이전트가 호출되면 서비스는 워크로드 액세스 토큰 생성을 자동으로 처리합니다.
-
런타임은 인바운드 자격 증명 공급자 OAuth 토큰(발급자, 서명)을 검증합니다.
-
런타임은 사용자 자격 증명을 나타내는 OAuth 토큰에서 발급자 및 하위 클레임을 추출합니다.
-
런타임은 에이전트의 연결된 워크로드 자격 증명을 가져옵니다.
-
런타임은 사용자 자격 증명과 에이전트 워크로드 자격 증명을 모두
GetWorkloadAccessTokenForJWT사용하여 호출합니다. -
런타임은 호출 페이로드 헤더의 일부로 워크로드 액세스 토큰을 에이전트 코드에 전달합니다.
이 자동 프로세스를 통해 에이전트는 수동 개입 없이 적절한 범위의 토큰을 수신할 수 있습니다.
워크로드 액세스 토큰을 수동으로 검색하는 방법
에이전트의 최종 사용자를 식별하는 방법에 따라 워크로드 액세스 토큰을 검색하는 데 사용할 수 있는 두 가지 패턴이 있습니다.
패턴 1: JWT 기반 식별(프로덕션에 권장)
에이전트의 호출자에게 최종 사용자에 대해 자격 증명 공급자가 발급한 JWT가 있는 경우를 사용하여 워크로드 액세스 토큰을 요청합니다GetWorkloadAccessTokenForJWT. JWT를 제공하면 AgentCore 자격 증명은 토큰이 올바르게 서명되고 만료되지 않았는지 확인하고 “iss” 및 “sub” 클레임을 사용하여 사용자를 고유하게 식별합니다. 에이전트가 사용자를 대신하여 저장한 자격 증명은 암호화 방식으로 확인된이 자격 증명과 연결되며, 향후 검색에는 동일한 자격 증명을 가진 유효한 워크로드 액세스 토큰이 필요합니다.
다음과 같은 경우이 패턴을 사용합니다.
-
애플리케이션이 자격 증명 공급자(Cognito, Auth0, Okta 등)와 통합됩니다.
-
최종 사용자의 자격 증명에 대한 암호화 증명이 필요합니다.
-
프로덕션에 배포하는 경우
패턴 2: UserId 기반 식별
에이전트의 호출자에게 최종 사용자를 식별하는 JWT가 없는 경우 사용자를 식별하는 고유 문자열과 GetWorkloadAccessTokenForUserId 함께를 사용하여 워크로드 액세스 토큰을 요청합니다.
다음과 같은 경우이 패턴을 사용합니다.
-
애플리케이션은 자체 사용자 식별자를 관리하므로 고객 관리형 userId 문자열을 AgentCore Identity에 전달해야 합니다.
-
IdP 토큰을 아직 사용할 수 없는 개발 또는 빠른 시작 시나리오에 있는 경우
-
엔터프라이즈 아키텍처는 사용자 ID 업스트림을 확인하고 신뢰할 수 있는 식별자를 에이전트 워크로드에 전달합니다.
트레이드오프: 플랫폼은 userId를 불투명 문자열로 취급하며 인증된 최종 사용자 자격 증명에 대해 확인할 수 없습니다. 보안 바인딩은 올바른 userId를 전달하는 호출 워크로드와 적절하게 범위가 지정되는 IAM 정책에 의존합니다. 권장 제어는 섹션을 참조GetWorkloadAccessTokenForUserId API에 대한 보안 제어하세요.
코드 예제
아래 예제는 AgentCore SDK를 사용하여 다음 두 가지 방법을 사용하여 워크로드 액세스 토큰을 검색하는 방법을 보여줍니다.
from bedrock_agentcore.services.identity import IdentityClient identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user. # AgentCore Identity validates the JWT signature, issuer, and expiry. workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user. # Use this when a JWT is not available. The platform does not verify this string. workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)
GetWorkloadAccessTokenForUserId API에 대한 보안 제어
GetWorkloadAccessTokenForUserId API는 호출자가 제공한 사용자 식별자 문자열을 수락하고 해당 사용자-에이전트 페어로 범위가 지정된 워크로드 액세스 토큰을 발급합니다. 이 API는 고객 관리형 userId 문자열을 전달해야 하는 엔터프라이즈 고객과 개발 중에 사용 가능한 ID 제공업체(IdP) 토큰이 없는 빌더를 지원하도록 설계되었습니다.
중요
GetWorkloadAccessTokenForUserId를 사용하는 경우 플랫폼은 userId 값을 불투명 문자열로 취급하고 인증된 최종 사용자 자격 증명에 대해 확인하지 않습니다. 보안 바인딩은 올바른 userId를 전달하는 호출 워크로드와 적절하게 범위가 지정되는 IAM 정책에 전적으로 의존합니다. 애플리케이션이 최종 사용자를 식별하는 JWT에 액세스할 수 있는 경우 워크로드 액세스 토큰을 발급하기 전에 토큰의 발급자, 서명 및 만료를 검증하는 GetWorkloadAccessTokenForJWT 대신를 사용합니다.
GetWorkloadAccessTokenForUserId API는 무단 액세스를 방지하기 위해 여러 보안 제어를 구현합니다.
-
워크로드 자격 증명 검증 - API는 요청 자격 증명에 지정된 워크로드 자격 증명을 대신하여 작업할 수 있는 권한이 있는지 확인합니다.
-
서비스 관리형 자격 증명 제한 - 런타임 관리형 및 게이트웨이 관리형 워크로드 자격 증명은 토큰을 직접 검색할 수 없습니다. 이렇게 하면 에이전트가 오용을 위해 토큰을 추출할 수 없습니다.
-
IAM 권한 요구 사항 - 발신자는
GetWorkloadAccessToken, 및GetWorkloadAccessTokenForUserId를 포함한 적절한 IAM 권한이 있어야 합니다.GetWorkloadAccessTokenForJWT -
토큰 범위 지정 - 토큰은 특정 사용자-에이전트 페어로 범위가 지정되므로 한 사용자에게 저장된 자격 증명에 다른 사용자가 액세스할 수 없습니다.
-
여러 자격 증명 공급자에 대한 사용자 ID 파티셔닝 - 여러 자격 증명 공급자를 사용하는 경우 패턴을 사용하여 사용자 IDs를 파티셔닝
provider_id+user_id하여 서로 다른 공급자 간의 사용자 충돌을 방지합니다. 예를 들어cognito+user123및auth0+user123를 사용하여 서로 다른 자격 증명 공급자 간에 식별자가 동일한 사용자를 구분합니다.
권장 보안 제어
플랫폼에서 userId 문자열을 확인할 수 없으므로이 API에 전달되는 값의 무결성을 보장할 책임은 사용자에게 있습니다. 다음 컨트롤을 적용합니다.
-
JWT를 사용할 수 있는
GetWorkloadAccessTokenForJWT경우 선호 - JWT 기반 경로는 토큰의 발급자와 서명을 검증하여 사용자 자격 증명의 암호화 증명을 제공합니다. JWT를 사용할 수 없는GetWorkloadAccessTokenForUserId경우에만 사용합니다. -
신뢰할 수 있는 소스에서 userId 파생 - userId 값은 임의의 클라이언트 제공 값을 수락하는 대신 인증된 보안 주체의 컨텍스트(예: IAM 호출자 자격 증명, 세션 속성 또는 업스트림 자격 증명 확인 계층)에서 파생되어야 합니다. 이렇게 하면 인증된 호출자가 다른 사용자를 가장하는 것을 방지할 수 있습니다.
-
IAM 권한 제한 - 신뢰할 수 있는 보안 주체만
bedrock-agentcore:GetWorkloadAccessTokenForUserId권한을 가져야 합니다. 이 권한의 범위를 특정 워크로드 자격 증명 리소스로 지정합니다. 관리형 정책 또는 와일드카드 리소스 문을 통해 광범위하게 부여하지 마세요. -
필요하지 않은
GetWorkloadAccessTokenForUserId위치 거부 - 항상 JWT를 사용할 수 있는 워크로드의 경우 userId 경로가 사용되지 않도록 IAM 정책에서 작업을 명시적으로 거부합니다.{ "Statement": [ { "Sid": "DenyForUserIdAccess", "Effect": "Deny", "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId", "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default" } ] } -
감사 로깅 구현 - 인증된 IAM 보안 주체와 전달되는 userId 값 간의 관계를 로깅합니다. AWS CloudTrail을 사용하여
GetWorkloadAccessTokenForUserId호출을 모니터링하고 예상치 못한 userId 값을 감지합니다.
"WorkloadIdentity가 서비스에 연결되어 있고 호출자가 액세스 토큰을 검색할 수 없습니다"라는 오류가 발생하는 경우 이는 워크로드 자격 증명이 런타임 또는 게이트웨이에서 관리되며 토큰을 직접 검색할 수 없음을 나타냅니다. 이 제한은 보안 경계를 유지하고 무단 토큰 액세스를 방지하는 데 도움이 됩니다.
추가 보안 제어를 위해 세분화된 액세스 정책을 구현하여 특정 자격 증명 공급자에 액세스할 수 있는 워크로드 자격 증명을 제한할 수 있습니다. 자세한 내용은 워크로드 자격 증명별로 자격 증명 공급자에 대한 액세스 범위 축소를 참조하세요.
