상담사의 자체 ID를 사용하여 외부 서비스에 인증

Google Cloud 에서 호스팅되는 에이전트는 에이전트 아이덴티티에서 OpenID Connect (OIDC) ID 토큰을 요청하여 Cloud Run 또는 Google Kubernetes Engine (GKE)과 같은 Google Cloud 런타임에서 호스팅되는 도구 및 서비스에 자체 ID를 사용하여 인증할 수 있습니다. 에이전트는 이러한 ID 토큰을 사용하여 서드 파티 클라우드 플랫폼 (예: Amazon Web Services (AWS) 및 Microsoft Azure), 맞춤 API, API 게이트웨이, 온프레미스 백엔드를 인증할 수도 있습니다.

에이전트가 자체 권한으로 외부 서비스에 액세스하면 에이전트 ID가 OpenID Connect (OIDC) ID 토큰을 발급합니다. 이 JSON 웹 토큰 (JWT)은 에이전트의 SPIFFE ID를 어설션하며 에이전트의 트러스트 도메인 (관리형 워크로드 아이덴티티 풀)의 발급자 키로 서명됩니다. 외부 시스템은 Google Cloud Security Token Service에서 호스팅하는 공개 엔드포인트를 통해 Google Cloud 사용자 인증 정보나 SDK 없이 이러한 토큰을 확인할 수 있습니다.

  • OpenID 제공업체 메타데이터와 공개 키 엔드포인트(jwks_uri)를 게시하는 OpenID Connect Discovery 1.0 엔드포인트 (/.well-known/openid-configuration)
  • 에이전트 ID 토큰의 서명을 확인하는 데 사용되는 활성 공개 키를 제공하는 JSON 웹 키 세트 (JWKS) 엔드포인트 (/openid/jwks)

시작하기 전에

  1. 올바른 인증 방법을 선택했는지 확인합니다. 에이전트 아이덴티티 개요에서 SPIFFE ID, 트러스트 도메인, 에이전트 사용자 인증 정보가 작동하는 방식을 검토합니다.
  2. 에이전트 ID가 사용 설정된 에이전트를 만들고 배포합니다.
  3. 외부 서비스 또는 ID 공급업체가 다음 요구사항을 충족하는지 확인합니다.
  4. 에이전트와 타겟 외부 서비스의 다음 구성 값을 확인합니다.
    • 발급기관 URL (iss 클레임): 조직(https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) 또는 프로젝트(https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN)의 워크로드 아이덴티티 풀 발급기관 URL입니다.
    • 허용된 대상 (aud 클레임): ID 토큰을 검증할 때 외부 서비스 또는 ID 프로바이더가 예상하는 대상 URI입니다.
  5. 이 작업을 완료하는 데 필요한 역할이 있는지 확인합니다.

필요한 역할

에이전트 ID로 에이전트를 배포하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

  • Gemini Enterprise Agent Platform의 Agent Runtime에 에이전트를 배포하려면 Vertex AI 사용자 (roles/aiplatform.user)여야 합니다.
  • Cloud Run에 에이전트 서비스를 배포합니다. Cloud Run 관리자 (roles/run.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 에이전트 아이덴티티로 에이전트를 배포하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

에이전트 아이덴티티로 에이전트를 배포하려면 다음 권한이 필요합니다.

  • Gemini Enterprise Agent Platform의 Agent Runtime에 에이전트를 배포합니다.
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Cloud Run에 에이전트 서비스 배포:
    • run.services.create
    • run.services.update

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

에이전트의 OIDC ID 토큰 가져오기

OIDC ID 토큰을 획득하여 외부 서비스로 전송하도록 에이전트를 구성하려면 다음 작업을 완료하세요.

  1. 에이전트 아이덴티티로 에이전트 구성하기
  2. 애플리케이션 코드에서 OIDC ID 토큰 요청

에이전트 아이덴티티로 에이전트 구성

에이전트를 배포할 때 에이전트 아이덴티티를 사용 설정합니다.

  • Gemini Enterprise Agent Platform의 에이전트 런타임에 에이전트를 배포하는 경우 identity_type을 AGENT_IDENTITY로 설정합니다.

    remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

  • 컨테이너화된 에이전트 서비스를 Cloud Run에 배포하는 경우 --identity-type=agent-identity 플래그를 전달합니다.

    gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated

    다음을 바꿉니다.

    • SERVICE_NAME: Cloud Run 서비스의 이름입니다.
    • IMAGE_URL: 에이전트의 컨테이너 이미지 URL입니다.

애플리케이션 코드에서 OIDC ID 토큰 요청

에이전트의 애플리케이션 코드에서 Google Auth 클라이언트 라이브러리를 사용하여 타겟 외부 잠재고객의 OIDC ID 토큰을 요청합니다. 클라이언트 라이브러리는 메타데이터 서버에서 토큰 생성, 로컬 캐싱, 자동 갱신을 처리합니다.

기본적으로 외부 대상에 발급된 OIDC ID 토큰은 런타임 인증서에 바인딩되지 않습니다.

다음 예에서는 google-auth 라이브러리를 사용하여 OIDC ID 토큰을 요청하고 이를 나가는 요청에 Bearer 토큰으로 연결합니다.

Python

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import id_token

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

다음을 바꿉니다.

  • EXTERNAL_SERVICE_AUDIENCE: 수신 서비스에서 예상하는 대상 URI입니다 (예: bedrock.us-east-1.amazonaws.com 또는 api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: 에이전트가 호출하는 외부 API 또는 백엔드 엔드포인트의 URL입니다.

다른 프로그래밍 언어(Go, Node.js, Java 포함)의 클라이언트 라이브러리 안내 및 예시는 ID 토큰 가져오기를 참고하세요. 이러한 언어의 현재 클라이언트 라이브러리 버전은 --identity-type=agent-identity를 지원하지만 기본적으로 바운드 토큰을 사용하지는 않습니다.

에이전트 아이덴티티 ID 토큰 확인

외부 서비스가 에이전트로부터 OIDC ID 토큰을 수신하면 대상 서비스에 따라 다음 방법 중 하나를 사용하여 토큰을 확인합니다.

기본 제공 워크로드 아이덴티티 제휴 사용

수신 서비스가 기본 IAM 인증 또는 OIDC 워크로드 아이덴티티 제휴를 지원하는 클라우드 플랫폼에서 실행되는 경우 맞춤 토큰 확인 코드를 작성할 필요가 없습니다.

  • Cloud Run: 수신 서비스가 인증된 인그레스(--no-allow-unauthenticated)를 사용하여 Cloud Run에서 실행되는 경우 Cloud Run은 인그레스 레이어에서 수신되는 에이전트 아이덴티티 토큰을 검증합니다. 수신 서비스에서 호출 에이전트에 Cloud Run 호출자 (roles/run.invoker) 역할을 부여합니다. 자세한 내용은 Cloud Run에서 MCP 서버에 인증을 참고하세요.

    서비스에서 인증되지 않은 인그레스를 허용하고 애플리케이션 코드에서 토큰을 확인하는 경우 프로그래매틱 방식으로 토큰 확인을 참고하세요.

  • Amazon Bedrock:Google Cloud 보안 토큰 서비스 검색 URL 또는 발급자 URL과 예상 대상을 지정하여 인바운드 JWT 인증을 구성합니다. 자세한 내용은 AWS 문서의 인바운드 JWT 승인자 구성을 참고하세요.

  • Microsoft Entra ID: 기타 발급기관 시나리오를 사용하여 제휴 ID 사용자 인증 정보를 구성합니다. Google Cloud 보안 토큰 서비스 발급자 URL, 예상 대상, 주체 식별자 (sub 클레임)를 지정합니다. 자세한 내용은 Microsoft Learn 문서의 앱과 외부 ID 프로바이더 간의 트러스트 관계 만들기를 참고하세요.

프로그래매틱 방식으로 토큰 확인

에이전트가 맞춤 API, 마이크로서비스, API 게이트웨이 또는 온프레미스 워크로드에 요청을 전송하는 경우 수신 서비스는 액세스 권한을 부여하기 전에 수신되는 OIDC ID 토큰을 확인해야 합니다. 일반적으로 에이전트는 Authorization: Bearer TOKEN HTTP 헤더에서 이 토큰을 전달합니다.

수신 ID 토큰을 프로그래매틱 방식으로 확인하려면 다음 작업을 완료하세요.

  1. 토큰 발급자 URL 추출 및 검증
  2. 공개 서명 키 검색 및 캐싱
  3. 토큰 서명 및 클레임 확인
  4. 에이전트의 SPIFFE ID 승인

토큰 발급기관 URL 추출 및 검증

수신 요청이 도착하면 인증되지 않은 JWT 페이로드를 읽어 iss (발급자) 클레임을 추출합니다. 이 클레임에는 에이전트의 트러스트 도메인에 대한 워크로드 아이덴티티 풀의 URL이 포함됩니다. 이 URL은 탐색 문서와 공개 서명 키의 기본 URL 역할을 합니다.

아웃바운드 네트워크 요청을 하기 전에 iss 클레임이 조직 또는 프로젝트의 예상 Google Cloud Security Token Service 워크로드 아이덴티티 풀 URL과 일치하는지 확인합니다.

  • 조직 수준 신뢰 도메인:

    https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN

    예를 들어 ID가 123456789012인 조직의 경우 TRUST_DOMAIN은 agents.global.org-123456789012.system.id.goog입니다.

  • 프로젝트 수준 신뢰 도메인 (조직이 없는 프로젝트의 경우):

    https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN

    예를 들어 번호가 9876543210인 프로젝트의 경우 TRUST_DOMAIN는 agents.global.proj-9876543210.system.id.goog입니다.

공개 서명 키 검색 및 캐싱

발급자 URL을 검증한 후 Google Cloud 보안 토큰 서비스에서 공개 서명 키를 가져와 캐시합니다.

  1. OpenID Connect 탐색 엔드포인트 쿼리: 기본 발급기관 URL에 /.well-known/openid-configuration를 추가하고 인증되지 않은 HTTP GET 요청을 보냅니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • ORGANIZATION_ID: Google Cloud조직 ID입니다. 조직이 없는 프로젝트의 경우 organizations/ORGANIZATION_ID를 projects/PROJECT_NUMBER로 바꿉니다.
    • TRUST_DOMAIN: 에이전트의 신뢰 도메인 워크로드 아이덴티티 풀 ID입니다 (예: agents.global.org-123456789012.system.id.goog).

    HTTP 메서드 및 URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    요청이 성공하면 HTTP 200 OK 상태와 jwks_uri 필드를 비롯한 OpenID 제공업체 메타데이터가 포함된 JSON 객체가 반환됩니다.

    {
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. JSON 웹 키 세트 (JWKS) 엔드포인트 쿼리: 인증되지 않은 HTTP GET 요청을 OpenID 제공업체 메타데이터에 반환된 jwks_uri URL로 보냅니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • ORGANIZATION_ID: Google Cloud조직 ID입니다. 조직이 없는 프로젝트의 경우 organizations/ORGANIZATION_ID를 projects/PROJECT_NUMBER로 바꿉니다.
    • TRUST_DOMAIN: 에이전트의 신뢰 도메인 워크로드 아이덴티티 풀 ID입니다 (예: agents.global.org-123456789012.system.id.goog).

    HTTP 메서드 및 URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    요청이 성공하면 HTTP 200 OK 상태와 RFC 7517에 따라 형식이 지정된 공개 키 배열이 포함된 JSON 객체가 반환됩니다.

    {
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}

  3. 탐색 문서 및 키 캐싱: OpenID Connect 검색 엔드포인트와 JWKS 엔드포인트의 응답에는 다음 HTTP 캐시 헤더가 포함됩니다.

    Cache-Control: public, max-age=86400, must-revalidate

    최대 24시간(86400초) 동안 탐색 문서와 JWKS를 캐시하여 확인 성능을 개선하고 비율 제한을 방지합니다.

    Google Cloud 는 워크로드 아이덴티티 풀의 비공개 및 공개 서명 키를 주기적으로 순환합니다. 인증자가 로컬 키 캐시에 없는 kid (키 ID)가 있는 수신 토큰을 수신하는 경우 토큰을 거부하기 전에 /openid/jwks 엔드포인트에서 최신 JWKS를 가져옵니다.

    검색 또는 JWKS 엔드포인트를 쿼리할 때 HTTP 오류가 발생하면 에이전트 아이덴티티 인증 문제 해결을 참고하세요.

토큰 서명 및 클레임 확인

토큰 서명을 암호화 방식으로 확인하고 JWT 클레임을 검증하려면 표준 OIDC 또는 JWT 확인 라이브러리 (예: Google Tink)를 사용하고 다음을 실행하세요.

  1. 서명: 캐시된 JWKS에서 JWT 헤더의 kid (키 ID)와 일치하는 공개 키를 찾습니다. alg 필드 (RS256)에 지정된 알고리즘을 사용하여 서명을 검증합니다. 이전 버전과의 호환성을 위해 알고리즘 유형을 하드코딩하는 대신 JWKS에서 alg 및 kty 필드를 동적으로 검사합니다.
  2. 발급기관 (iss): iss 클레임이 신뢰 도메인의 신뢰할 수 있는Google Cloud 워크로드 아이덴티티 풀 발급기관 URL과 일치하는지 확인합니다.
  3. 대상 (aud): aud 클레임이 서비스의 구성된 대상 식별자와 일치하는지 확인합니다.
  4. 발급 시간 (iat) 및 만료 시간 (exp): iat 클레임이 과거에 있고 현재 시간이 exp 클레임보다 빠른지 확인합니다 (1~2분과 같은 작은 시계 편차 허용).

다음 예에서는 Google Tink (tink.jwt)를 사용하여 JWKS JSON 페이로드를 기준으로 에이전트 아이덴티티 ID 토큰을 확인합니다.

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

에이전트의 SPIFFE ID 승인

토큰의 서명과 표준 클레임을 확인한 후 확인된 sub (주체) 클레임을 검사하여 요청을 승인하고 호출 에이전트를 감사 로그에 기록합니다.

sub 클레임에는 에이전트의 고유 SPIFFE ID가 포함됩니다. 예를 들면 다음과 같습니다.

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

서비스의 승인 로직에서 인증된 sub 클레임을 신뢰할 수 있는 에이전트 SPIFFE ID (또는 신뢰 도메인 접두사)의 허용 목록과 비교한 후 보호된 리소스에 대한 액세스 권한을 부여합니다.

다음 단계