Usa WIF con Google Cloud

Qualsiasi ambiente di calcolo Google Cloud con accesso al server di 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 ad esso collegato. L'issuer 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'issuer di Google presso Anthropic, associare un service account Google a un service account Anthropic e far sì che il tuo workload scambi il proprio token di identità con un token di accesso di breve durata per la Claude API.



Prerequisiti

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



Configura Google Cloud

Google emette automaticamente token di identità per qualsiasi workload con un service account collegato. Non c'è nulla da abilitare sul lato Google oltre a collegare il service account corretto, ma i passaggi differiscono leggermente tra il compute standard e 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
}



Configura 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'issuer, nella creazione di un service account e nella creazione di una federation rule.

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:

Federation issuer: Google pubblica il proprio documento di discovery OIDC pubblicamente, quindi usa la modalità discovery. Questo singolo issuer copre ogni superficie di Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine e GKE con Workload Identity). Differenzia i workload con le rule, non con gli issuer.

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

Federation rule: Effettua il match 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 rule 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": "[email protected]"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}



Acquisisci e usa il token

All'interno del tuo workload Google Cloud, recupera il token di identità dal server di metadati, scambialo su POST /v1/oauth/token e usa il bearer token restituito per chiamare la Claude API. Ogni SDK di Anthropic gestisce per te il ciclo di scambio e aggiornamento quando fornisci un callable token-provider che restituisce un token di identità aggiornato dal server di 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à di Google scadono dopo circa un'ora. Gli SDK richiamano nuovamente il token provider e ripetono lo scambio automaticamente prima della scadenza. Per gli script shell che vengono eseguiti più a lungo dell'expires_in del token di accesso, aggiorna con un timer e ripeti lo scambio.



Verifica la configurazione

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

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, che aud sia https://api.anthropic.com e che email corrisponda al valore nella tua federation rule. 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. In caso di 400 invalid_grant, consulta Risolvere i problemi di uno scambio non riuscito; la causa più comune sul lato Google Cloud è l'assenza del claim email (richiedi il token con format=full in modo che venga incluso).



Limita l'ambito della tua rule

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

• Effettua il match esatto su sub: 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 insieme a sub in modo che sia l'ID stabile sia l'indirizzo leggibile debbano corrispondere.
• Fissa l'audience: Imposta audience sul valore esatto che richiedi al server di 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 rule ai nodi di un solo progetto.



Prossimi passi

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