Google Cloud에서 WIF 사용하기

인스턴스 메타데이터 서버에 접근할 수 있는 모든 Google Cloud 컴퓨팅 환경(Cloud Run, Cloud Functions, App Engine, Compute Engine(GCE), Workload Identity가 활성화된 GKE)은 연결된 서비스 계정에 대해 Google이 서명한 ID 토큰을 요청할 수 있습니다. 토큰의 발급자는 https://accounts.google.com이며, Anthropic은 추가적인 Google Cloud 구성 없이 표준 OIDC 디스커버리를 통해 이를 직접 검증할 수 있습니다.

이 가이드에서는 Google 발급자를 Anthropic에 등록하고, Google 서비스 계정을 Anthropic 서비스 계정에 바인딩하며, 워크로드가 자신의 ID 토큰을 단기 Claude API 액세스 토큰으로 교환하도록 하는 방법을 설명합니다.

사전 요구 사항

• WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
• Cloud Run, Cloud Functions, App Engine, Compute Engine 또는 GKE에서 실행 중인 워크로드가 있는 Google Cloud 프로젝트.
• 해당 워크로드에 연결된 사용자 관리 Google 서비스 계정(Compute Engine 기본 서비스 계정이 아님).
• Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 수 있는 권한.

Google Cloud 구성

Google은 서비스 계정이 연결된 모든 워크로드에 자동으로 ID 토큰을 발급합니다. 올바른 서비스 계정을 연결하는 것 외에 Google 측에서 활성화할 것은 없지만, 표준 컴퓨팅과 GKE 간에 단계가 약간 다릅니다.

Anthropic 구성

설정 안내를 따라 Claude Console에서 페더레이션 발급자를 등록하고, Anthropic 서비스 계정을 생성하고, 페더레이션 규칙을 생성하세요. 다음의 Google Cloud 전용 값을 사용하세요.

페더레이션 발급자: Google은 OIDC 디스커버리 문서를 공개적으로 게시하므로 디스커버리 모드를 사용하세요. 이 단일 발급자는 모든 Google Cloud 환경(Cloud Run, GCE, Cloud Functions, App Engine, Workload Identity가 활성화된 GKE)을 포괄합니다. 워크로드는 발급자가 아닌 규칙으로 구분하세요.

{
  "name": "gcp",
  "issuer_url": "https://accounts.google.com",
  "jwks_source": "discovery"
}

페더레이션 규칙: sub와 email 클레임 모두를 매칭하세요. email은 읽을 수 있는 서비스 계정 주소이고, sub는 Google이 절대 재사용하지 않는 서비스 계정의 숫자 고유 ID이므로, 이를 고정하면 서비스 계정이 삭제되고 나중에 동일한 이메일로 새 계정이 생성되더라도 규칙이 보호됩니다. 고유 ID는 gcloud iam service-accounts describe SA_EMAIL --format='value(uniqueId)'로 확인할 수 있습니다.

{
  "name": "gcp-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "https://api.anthropic.com",
    "claims": {
      "sub": "104892101234567890123",
      "email": "[email protected]"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

토큰 획득 및 사용

Google Cloud 워크로드 내부에서 메타데이터 서버로부터 ID 토큰을 가져오고, POST /v1/oauth/token에서 교환한 다음, 반환된 베어러 토큰을 사용하여 Claude API를 호출하세요. 다음 예제와 같이 메타데이터 서버에서 새로운 ID 토큰을 반환하는 토큰 제공자 콜러블을 제공하면, 각 Anthropic SDK가 교환 및 갱신 루프를 자동으로 처리합니다.

import os
import anthropic
import google.auth.transport.requests
import google.oauth2.id_token
from anthropic import WorkloadIdentityCredentials

AUDIENCE = "https://api.anthropic.com"


def fetch_google_identity_token() -> str:
    request = google.auth.transport.requests.Request()
    return google.oauth2.id_token.fetch_id_token(request, AUDIENCE)


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_google_identity_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(message.content[0].text)

Google ID 토큰은 약 1시간 후에 만료됩니다. SDK는 만료 전에 토큰 제공자를 자동으로 다시 호출하고 재교환합니다. 액세스 토큰의 expires_in보다 오래 실행되는 셸 스크립트의 경우, 타이머를 사용하여 갱신하고 교환을 반복하세요.

설정 확인

워크로드 내부에서 ID 토큰을 디코딩하고 클레임이 규칙과 일치하는지 확인하세요:

curl -sS -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full" \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

iss가 https://accounts.google.com이고, aud가 https://api.anthropic.com이며, email이 페더레이션 규칙의 값과 일치하는지 확인하세요. 그런 다음 이전 섹션의 교환을 실행하세요. 교환이 성공하면 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값이 반환됩니다. 400 invalid_grant 오류가 발생하면 실패한 교환 문제 해결을 참조하세요. Google Cloud 측에서 가장 흔한 원인은 email 클레임이 누락된 경우입니다(포함되도록 format=full로 토큰을 요청하세요).

규칙 범위 제한

규칙의 match 블록을 사용 사례에 맞는 가장 좁은 범위로 제한하세요:

• sub를 정확히 매칭: claims.sub에 전체 숫자 고유 ID를 설정하고 Google 토큰에는 절대 subject_prefix를 사용하지 마세요.
• email 클레임 고정: sub와 함께 claims.email을 추가하여 안정적인 ID와 읽을 수 있는 주소가 모두 일치해야 하도록 하세요.
• audience 고정: audience를 메타데이터 서버에서 요청하는 정확한 값으로 설정하여 다른 소비자를 위해 발급된 토큰이 거부되도록 하세요.
• GKE에서 프로젝트 고정: format=full 토큰의 경우, claims.google.compute_engine.project_id == "my-project"와 같은 condition을 추가하여 규칙을 하나의 프로젝트 노드로 제한하세요.

다음 단계

• 전체 리소스 모델과 SDK 자격 증명 우선순위에 대해서는 Workload Identity Federation 페이지를 읽어보세요.
• 환경별(프로덕션, 스테이징)로 별도의 페더레이션 규칙을 추가하여 다른 환경에 영향을 주지 않고 하나를 취소할 수 있도록 하세요.