Google Cloud에서 WIF 사용하기

인스턴스 메타데이터 서버에 접근할 수 있는 모든 Google Cloud 컴퓨팅 환경(Cloud Run, Cloud Functions, App Engine, Compute Engine(GCE), Workload Identity가 적용된 GKE)은 연결된 서비스 계정에 대해 Google이 서명한 "identity token"(ID 토큰)을 요청할 수 있습니다. 토큰의 발급자(issuer)는 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 간에는 단계가 약간 다릅니다.

gcloud run deploy my-service \
  --service-account inference-worker@my-project.iam.gserviceaccount.com

GET http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full
Metadata-Flavor: Google

gcloud auth print-identity-token \
  --audiences="https://api.anthropic.com" \
  --include-email

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.anthropic.com",
  "sub": "104892...",
  "azp": "104892...",
  "email": "inference-worker@my-project.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1775527120
}

Anthropic 구성

Claude Console에서 Settings → Workload identity를 열고 Connect workload를 클릭한 다음 Google Cloud 타일을 선택하세요. 마법사가 발급자 등록, 서비스 계정 생성, 페더레이션 규칙 생성 과정을 안내합니다.

마법사가 이러한 리소스를 대신 생성해 줍니다. 마법사에 입력하든 Admin API로 전송하든 다음 값을 사용하세요:

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

{
  "name": "gcp",
  "issuer_url": "https://accounts.google.com",
  "jwks": { "type": "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": "inference-worker@my-project.iam.gserviceaccount.com"
    }
  },
  "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 토큰을 반환하는 토큰 제공자 callable을 제공하면, 각 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(next(block.text for block in message.content if block.type == "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 값이 반환됩니다. 교환이 불투명한 401 authentication_error 응답(메시지 Authentication failed)으로 실패하면, 인증 기록 페이지에서 거부 사유를 확인하고 실패한 교환 문제 해결을 참조하세요. 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 페이지를 읽어보세요.
• 환경(프로덕션, 스테이징)별로 별도의 페더레이션 규칙을 추가하여 다른 환경에 영향을 주지 않고 하나를 취소할 수 있도록 하세요.