Usare WIF con Google Cloud

Qualsiasi ambiente di calcolo Google Cloud con accesso al server dei metadati dell'istanza (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE) e GKE con Workload Identity) può richiedere un token di identità firmato da Google per il service account associato. L'emittente del token è https://accounts.google.com e Anthropic può convalidarlo direttamente tramite la discovery OIDC standard, senza alcuna configurazione aggiuntiva di Google Cloud.

Questa guida mostra come registrare l'emittente Google presso Anthropic, associare un service account Google a un service account Anthropic e fare in modo che il tuo carico di lavoro scambi il proprio token di identità con un token di accesso alla Claude API di breve durata.

Prerequisiti

• Familiarità con i concetti di WIF: service account, emittenti di federazione e regole di federazione.
• Un progetto Google Cloud con un carico di lavoro in esecuzione su Cloud Run, Cloud Functions, App Engine, Compute Engine o GKE.
• Un service account Google gestito dall'utente associato a quel carico di lavoro (non il service account predefinito di Compute Engine).
• Autorizzazione a creare service account, emittenti di federazione e regole di federazione nella Claude Console per la tua organizzazione Anthropic.

Configurare Google Cloud

Google emette automaticamente token di identità per qualsiasi carico di lavoro con un service account associato. Non c'è nulla da abilitare lato Google oltre ad associare il service account corretto, ma i passaggi differiscono leggermente tra il calcolo standard e 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
}

Configurare Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro Google Cloud. La procedura guidata ti accompagna nella registrazione dell'emittente, nella creazione di un service account e nella creazione di una regola di federazione.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Emittente di federazione: Google pubblica il proprio documento di discovery OIDC pubblicamente, quindi usa la modalità discovery. Questo singolo emittente copre ogni superficie Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine e GKE con Workload Identity). Differenzia i carichi di lavoro con le regole, non con gli emittenti.

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

Regola di federazione: Esegui la corrispondenza sia sul claim sub che sul claim email. email è l'indirizzo leggibile del service account; sub è l'ID univoco numerico del service account, che Google non riutilizza mai, quindi fissarlo protegge la regola nel caso in cui il service account venga eliminato e ne venga successivamente creato uno nuovo con la stessa email. Trova l'ID univoco con 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
}

Acquisire e usare il token

All'interno del tuo carico di lavoro Google Cloud, recupera il token di identità dal server dei metadati, scambialo presso POST /v1/oauth/token e usa il bearer token restituito per chiamare la Claude API. Ogni SDK Anthropic gestisce per te il ciclo di scambio e rinnovo quando fornisci un callable token-provider che restituisce un token di identità aggiornato dal server dei metadati, come mostrato negli esempi seguenti.

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"))

I token di identità Google scadono dopo circa un'ora. Gli SDK richiamano il token provider e rieseguono lo scambio automaticamente prima della scadenza. Per gli script shell che durano più a lungo dell'expires_in del token di accesso, esegui il rinnovo con un timer e ripeti lo scambio.

Verificare la configurazione

Dall'interno del tuo carico di lavoro, decodifica il token di identità e conferma che i claim corrispondano alla tua regola:

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'

Verifica che iss sia https://accounts.google.com, aud sia https://api.anthropic.com e email corrisponda al valore nella tua regola di federazione. Quindi esegui lo scambio della sezione precedente. Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto e consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato Google Cloud è l'assenza del claim email (richiedi il token con format=full in modo che venga incluso).

Limitare l'ambito della regola

Vincola il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

• Fai corrispondere sub esattamente: Imposta l'ID univoco numerico completo in claims.sub e non usare mai subject_prefix per i token Google.
• Fissa il claim email: Aggiungi claims.email accanto a sub in modo che debbano corrispondere sia l'ID stabile sia l'indirizzo leggibile.
• Fissa l'audience: Imposta audience sul valore esatto che richiedi al server dei metadati, in modo che i token emessi per altri consumatori vengano rifiutati.
• Fissa il progetto su GKE: Per i token format=full, aggiungi una condition come claims.google.compute_engine.project_id == "my-project" per limitare la regola ai nodi di un solo progetto.

Passaggi successivi

• Leggi la pagina Workload Identity Federation per il modello completo delle risorse e la precedenza delle credenziali negli SDK.
• Aggiungi una regola di federazione separata per ogni ambiente (produzione, staging) in modo da poterne revocare una senza influire sulle altre.