Menggunakan WIF dengan Google Cloud

Setiap lingkungan komputasi Google Cloud yang memiliki akses ke server metadata instans (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 penemuan OIDC 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 token akses 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 untuk 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 kotak 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 penemuan OIDC-nya secara publik, jadi gunakan mode discovery. Satu issuer ini mencakup semua permukaan Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine, dan GKE dengan Workload Identity). Bedakan workload dengan rule, bukan dengan issuer.

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

Federation rule: Cocokkan klaim sub dan email sekaligus. email adalah alamat service account yang dapat dibaca; sub adalah ID unik numerik milik service account, yang tidak pernah digunakan ulang oleh Google, sehingga mengunci nilainya melindungi rule jika service account dihapus dan yang baru kemudian dibuat dengan email yang sama. Temukan ID unik tersebut 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 loop penukaran dan penyegaran untuk Anda ketika Anda menyediakan callable penyedia token yang mengembalikan token identitas baru dari server metadata, seperti yang ditunjukkan pada 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-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"))

Token identitas Google kedaluwarsa setelah kira-kira satu jam. SDK akan memanggil ulang penyedia token dan melakukan penukaran ulang secara otomatis sebelum kedaluwarsa. Untuk skrip shell yang berjalan lebih lama dari expires_in token akses, segarkan dengan timer dan ulangi penukaran.



Memverifikasi penyiapan

Dari dalam workload Anda, dekode token identitas dan pastikan klaimnya 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 di federation rule Anda. Kemudian jalankan penukaran dari bagian sebelumnya. Penukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Pada 400 invalid_grant, lihat Memecahkan masalah penukaran 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 menggunakan subject_prefix untuk token Google.
• Kunci klaim email: Tambahkan claims.email bersama sub sehingga ID yang stabil dan alamat yang dapat dibaca keduanya harus cocok.
• Kunci audience: Tetapkan audience ke nilai persis yang Anda minta dari server metadata sehingga token yang diterbitkan untuk konsumen lain akan ditolak.
• Kunci 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 saja.



Langkah selanjutnya

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