Menggunakan WIF dengan Google Cloud

Setiap lingkungan komputasi Google Cloud yang memiliki akses ke server metadata instance (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE), dan GKE dengan Workload Identity) dapat meminta token identitas yang ditandatangani Google untuk service account yang terpasang padanya. Issuer token tersebut adalah https://accounts.google.com, dan Anthropic dapat memvalidasinya secara langsung melalui OIDC discovery standar, tanpa memerlukan konfigurasi Google Cloud tambahan.

Panduan ini menunjukkan cara mendaftarkan issuer Google ke Anthropic, mengikat service account Google ke service account Anthropic, dan membuat workload Anda menukar token identitasnya dengan access token Claude API berumur pendek.



Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Proyek Google Cloud dengan workload yang berjalan di Cloud Run, Cloud Functions, App Engine, Compute Engine, atau GKE.
• Service account Google yang dikelola pengguna dan terpasang pada workload tersebut (bukan service account default Compute Engine).
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.



Mengonfigurasi Google Cloud

Google menerbitkan token identitas secara otomatis ke setiap workload yang memiliki service account terpasang. Tidak ada yang perlu diaktifkan di sisi Google selain memasang service account yang tepat, tetapi langkah-langkahnya sedikit berbeda antara komputasi standar dan GKE.

gcloud run deploy my-service \
  --service-account [email protected]

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": "[email protected]",
  "email_verified": true,
  "exp": 1775527120
}



Mengonfigurasi Anthropic

Di Claude Console, buka Settings → Workload identity, klik Connect workload, dan pilih tile Google Cloud. Wizard akan memandu Anda mendaftarkan issuer, membuat service account, dan membuat federation rule.

Wizard ini membuat sumber daya tersebut untuk Anda. Gunakan nilai-nilai berikut baik saat Anda memasukkannya di wizard maupun saat mengirimkannya ke Admin API:

Federation issuer: Google memublikasikan dokumen OIDC discovery-nya secara publik, jadi gunakan mode discovery. Satu issuer ini mencakup setiap permukaan Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine, dan GKE dengan Workload Identity). Bedakan workload dengan rule, bukan issuer.

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

Federation rule: Cocokkan pada klaim sub dan email sekaligus. email adalah alamat service account yang dapat dibaca; sub adalah ID unik numerik service account, yang tidak pernah digunakan kembali oleh Google, sehingga menyematkannya melindungi rule jika service account dihapus dan yang baru kemudian dibuat dengan email yang sama. Temukan ID unik dengan 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
}



Memperoleh dan menggunakan token

Di dalam workload Google Cloud Anda, ambil token identitas dari server metadata, tukarkan di POST /v1/oauth/token, dan gunakan bearer token yang dikembalikan untuk memanggil Claude API. Setiap SDK Anthropic menangani pertukaran dan loop refresh untuk Anda ketika Anda menyediakan callable token-provider yang mengembalikan token identitas baru dari server metadata, seperti yang ditunjukkan dalam contoh berikut.

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)

Token identitas Google kedaluwarsa setelah kira-kira satu jam. SDK akan memanggil ulang token provider dan menukar ulang secara otomatis sebelum kedaluwarsa. Untuk skrip shell yang berjalan lebih lama dari expires_in access token, lakukan refresh dengan timer dan ulangi pertukaran.



Memverifikasi penyiapan

Dari dalam workload Anda, dekode token identitas dan konfirmasikan bahwa klaim cocok dengan rule Anda:

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'

Periksa bahwa iss adalah https://accounts.google.com, aud adalah https://api.anthropic.com, dan email cocok dengan nilai dalam federation rule Anda. Kemudian jalankan pertukaran dari bagian sebelumnya. Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Pada 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum di sisi Google Cloud adalah klaim email yang hilang (minta token dengan format=full agar klaim tersebut disertakan).



Membatasi cakupan rule Anda

Kunci blok match pada rule ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:

• Cocokkan sub secara persis: Tetapkan ID unik numerik lengkap di claims.sub dan jangan pernah gunakan subject_prefix untuk token Google.
• Sematkan klaim email: Tambahkan claims.email di samping sub sehingga ID stabil dan alamat yang dapat dibaca harus cocok keduanya.
• Sematkan audience: Tetapkan audience ke nilai persis yang Anda minta dari server metadata sehingga token yang dibuat untuk konsumen lain ditolak.
• Sematkan proyek pada GKE: Untuk token format=full, tambahkan condition seperti claims.google.compute_engine.project_id == "my-project" untuk membatasi rule ke node dari satu proyek.



Langkah selanjutnya

• Baca halaman Workload Identity Federation untuk model resource lengkap dan urutan prioritas kredensial SDK.
• Tambahkan federation rule terpisah per lingkungan (produksi, staging) sehingga Anda dapat mencabut salah satunya tanpa memengaruhi yang lain.