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

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

에이전트 ID를 사용하면 에이전트가 Google Cloud 자체 ID를 사용하여 외부 서비스와 Cloud Run 또는 Google Kubernetes Engine (GKE)에서 호스팅되는 워크로드에 인증할 수 있습니다. OpenID Connect (OIDC) ID 토큰을 사용하면 에이전트를 Amazon Web Services (AWS) 및 Microsoft Azure와 같은 서드 파티 클라우드 플랫폼, 커스텀 API, API Gateway, 온프레미스 백엔드에 연결할 수 있습니다.

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

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

자체 ID를 사용하여 에이전트를 Google Cloud API 및 리소스에 인증하려면 에이전트의 자체 ID를 사용하여 인증 Google Cloud 을 참조하세요. 최종 사용자를 대신하여 서비스에 액세스하려면 인증 관리자를 사용하여 3-Legged OAuth로 인증을 참조하세요.

시작하기 전에

1. 올바른 인증 방법을 선택했는지 확인합니다. 에이전트 ID 개요에서 SPIFFE ID, 트러스트 도메인, 에이전트 사용자 인증 정보 가 어떻게 작동하는지 검토합니다.
2. 에이전트 ID가 사용 설정된 에이전트를 만들고 배포합니다.

3. 외부 서비스 또는 ID 공급업체가 다음 요구사항을 충족하는지 확인합니다.

   • OpenID Connect Discovery 1.0 및 JSON 웹 키 세트 (JWKS)를 사용하여 JSON 웹 토큰 (JWT)의 유효성 검사를 지원합니다.
   • 상호 TLS (mTLS)를 통해 인증서 바인딩을 적용하는 경우 클라이언트 인증서 인증을 TLS 1.3 (RFC 9846)에서 지원하고 cnf (x5t#S256) 클레임의 유효성을 RFC 8705 섹션 6.1에 따라 검사합니다.
   • https://sts.googleapis.com에 아웃바운드 HTTPS 요청을 전송하여 OpenID 제공업체 메타데이터와 공개 서명 키를 가져올 수 있습니다.

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)

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

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

필수 권한

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

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

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

참고: 외부 서비스 및 서드 파티 인증업체는 에이전트 아이덴티티에서 발급한 OIDC ID 토큰을 확인하는 데 IAM 역할 또는 Google Cloud 인증이 필요하지 않습니다. OpenID Connect Discovery(/.well-known/openid-configuration) 및 JSON 웹 키 세트 (/openid/jwks) 엔드포인트는 공개되어 있으며 인증되지 않습니다.

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

외부 서비스에 OIDC ID 토큰을 가져오고 전송하도록 에이전트를 구성하려면 다음 태스크를 완료하세요.

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

에이전트 ID로 에이전트 구성

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

• Gemini Enterprise Agent Platform의 Agent Runtime에 에이전트를 배포하는 경우 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 토큰을 요청합니다. 클라이언트 라이브러리는 메타데이터 서버에서 토큰 생성, 로컬 캐싱, 자동 갱신을 처리합니다.

기본적으로 지원되는 Google Auth 클라이언트 라이브러리는 토큰의 cnf (x5t#S256) 클레임에 인증서 디지털 지문을 포함하여 OIDC ID 토큰을 에이전트의 고유한 X.509 인증서에 암호화 방식으로 바인딩합니다. 수신 서비스는 상호 TLS (mTLS) 핸드셰이크 중에 제공된 클라이언트 인증서에 대해 이 클레임의 유효성을 선택적으로 검사하거나 인증서 바인딩을 적용하지 않는 경우 클레임을 무시할 수 있습니다.

Cloud Run은 ID 토큰에 cnf 클레임이 있는 경우 인증서 바인딩을 자동으로 적용합니다. 에이전트가 바인딩된 ID 토큰을 사용하여 Cloud Run 서비스를 호출하는 경우 mTLS 연결을 통해 mTLS 엔드포인트 (*.mtls.run.app)를 호출해야 합니다. 대신 표준 *.run.app URL을 계속 호출하려면 요청별로(예: Python에서 bind_id_token=False 설정) 또는 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false를 사용하여 런타임 환경 전체에서 인증서 바인딩을 선택 해제합니다. 지원되는 라이브러리 버전 및 예시는 인증서 바인딩된 토큰 선택 해제를 참조하세요.

mTLS를 통해 인증서 바인딩을 적용하는 엔드포인트를 호출할 때는 mTLS 핸드셰이크 중에 에이전트의 X.509 인증서를 제공하도록 클라이언트 세션을 구성합니다 (예: Python에서 authed_session.configure_mtls_channel() 호출).

다음 예에서는 google-auth 라이브러리를 사용하여 인증서 바인딩된 OIDC ID 토큰을 요청하고, 선택적으로 mTLS 채널을 구성하고, 토큰을 발신 요청의 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입니다.

Python (mTLS)

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

# 1. Specify the audience expected by the receiving service
# (for example, a regional Cloud Run mTLS URL or an on-premises mTLS endpoint).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create certificate-bound ID token credentials and configure the mTLS
# channel to present the agent's X.509 certificate.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)
authed_session.configure_mtls_channel()

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

다음을 바꿉니다.

• EXTERNAL_SERVICE_AUDIENCE: 수신 서비스에서 예상하는 잠재고객 URI (예: 리전 Cloud Run mTLS URL 또는 api.example.com).
• EXTERNAL_SERVICE_ENDPOINT: 에이전트가 호출하는 mTLS API 또는 백엔드 엔드포인트의 URL입니다.

Go, Node.js, Java와 같은 다른 언어의 클라이언트 라이브러리 안내 및 예시는 ID 토큰 가져오기를 참조하세요. 이러한 언어의 클라이언트 라이브러리는 --identity-type=agent-identity를 지원합니다. 인증서 바인딩된 ID 토큰을 지원하는 라이브러리는 기본적으로 토큰을 바인딩하며 개별 요청에 대해 선택 해제할 수 있습니다.

에이전트 ID 토큰 확인

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

• 관리형 클라우드 플랫폼 (예: Cloud Run, AWS, Microsoft Azure): 기본 제공 워크로드 아이덴티티 제휴를 사용하여 커스텀 인증 코드를 작성하지 않고도 수신 토큰을 확인합니다.
• 커스텀 백엔드 서비스, API 게이트웨이, 온프레미스 워크로드: 프로그래매틱 방식으로 토큰을 확인합니다 using the 공개 OpenID Connect Discovery 및 JWKS 엔드포인트를 사용하여.

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

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

• Cloud Run: 수신 서비스가 인증된 인그레스(--no-allow-unauthenticated)를 사용하여 Cloud Run에서 실행되는 경우 Cloud Run은 인그레스 레이어에서 수신 에이전트 ID 토큰의 유효성을 검사합니다. 토큰에 cnf 클레임이 포함된 경우 Cloud Run이 mTLS 핸드셰이크 중에 클라이언트 인증서의 유효성을 검사할 수 있도록 수신 서비스의 리전 mTLS URL(https://SERVICE_NAME-PROJECT_NUMBER.REGION.mtls.run.app)을 타겟팅하도록 호출 에이전트를 구성합니다. 수신 서비스에서 호출 에이전트에 Cloud Run 호출자 (roles/run.invoker) 역할을 부여합니다. 자세한 내용은 Cloud Run에서 MCP 서버에 인증을 참조하세요.

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

• Amazon Bedrock:Google Cloud Security Token Service 검색 URL 또는 발급기관 URL과 예상 잠재고객을 지정하여 인바운드 JWT 인증을 구성합니다. 자세한 내용은 AWS 문서의 인바운드 JWT 승인자 구성 을 참조하세요.

• Microsoft Entra ID: 기타 발급기관 시나리오로 제휴 ID 사용자 인증 정보를 구성합니다. Google Cloud Security Token Service 발급기관 URL, 예상 잠재고객, 주체 식별자 (sub 클레임)를 지정합니다. 자세한 내용은 Microsoft Learn 문서의 앱과 외부 ID 공급업체 간의 트러스트 관계 만들기 를 참조하세요.

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

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

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

1. 토큰 발급기관 URL 추출 및 유효성 검사
2. 공개 서명 키 검색 및 캐싱
3. 토큰 서명 및 클레임 확인
4. 선택사항: 인증서 바인딩 (cnf 클레임) 유효성 검사
5. 에이전트의 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입니다.

주의: 검색 엔드포인트에 HTTP 요청을 보내기 전에 항상 iss URL이 https://sts.googleapis.com/v1/로 시작하고 신뢰할 수 있는 Google Cloud 조직 또는 프로젝트에 속하는지 확인하세요.

공개 서명 키 검색 및 캐싱

발급기관 URL의 유효성을 검사한 후 공개 서명 키를 가져와 캐시합니다. Google Cloud Security Token Service:

1. OpenID Connect Discovery 엔드포인트 쿼리: 기본 발급기관 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

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

   curl(Linux, macOS, Cloud Shell)

   다음 명령어를 실행합니다.

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

   PowerShell(Windows)

   다음 명령어를 실행합니다.

   $headers = @{  }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration" | Select-Object -Expand Content

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

   {
     "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) 엔드포인트 쿼리: OpenID 제공업체 메타데이터에서 반환된 jwks_uri URL에 인증되지 않은 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/openid/jwks

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

   curl(Linux, macOS, Cloud Shell)

   다음 명령어를 실행합니다.

   curl -X GET \
        "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks"

   PowerShell(Windows)

   다음 명령어를 실행합니다.

   $headers = @{  }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks" | Select-Object -Expand Content

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

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

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

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

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

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

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

토큰 서명 및 클레임 확인

토큰 서명을 암호화 방식으로 확인하고 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)

선택사항: 인증서 바인딩 (cnf 클레임) 유효성 검사

수신 서비스가 mTLS를 통해 인증서 바인딩을 적용하는 경우 mTLS 핸드셰이크 중에 제공된 클라이언트 인증서에 대해 cnf (x5t#S256) 클레임의 유효성을 검사합니다.

1. 상호 TLS (mTLS) 종료: TLS 1.3 (RFC 9846)에 따라 TLS 핸드셰이크 중에 에이전트의 X.509 인증서를 요청하고 유효성을 검사하도록 서버 또는 인그레스 프록시를 구성합니다.
2. 인증서 지문 (x5t#S256) 계산: mTLS 연결에서 리프 X.509 클라이언트 인증서를 추출합니다. DER로 인코딩된 바이트에 대해 SHA-256 해시를 계산하고 = 패딩 없이 다이제스트를 base64url로 인코딩합니다.
3. cnf (x5t#S256) 클레임 유효성 검사: 확인된 JWT 페이로드에서 cnf 객체({"cnf": {"x5t#S256": "FINGERPRINT"}})를 검사하고 x5t#S256 값이 클라이언트 인증서 지문과 일치하는지 RFC 8705 섹션 6.1에 따라 확인합니다. 호출자가 mTLS를 통해 클라이언트 인증서를 제공하지 않았거나 디지털 지문이 일치하지 않는 경우 HTTP 401 Unauthorized 응답으로 요청을 거부합니다.

에이전트의 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 (또는 트러스트 도메인 프리픽스)의 허용 목록과 비교합니다.

다음 단계

• 에이전트 ID 인증 문제 해결
• 에이전트의 자체 ID를 사용하여 인증 Google Cloud
• 인증 관리자를 사용하여 2-Legged OAuth로 인증
• 인증 관리자를 사용하여 3-Legged OAuth로 인증
• 인증 관리자를 사용하여 API 키로 인증
• 에이전트 ID 개요