Utilizzare 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 proprio service account associato. L'issuer del token è https://accounts.google.com, e Anthropic può validarlo 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 l'API di Claude.

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 associato 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.

Configurare Google Cloud

Google emette automaticamente token di identità a qualsiasi workload 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.

Configurare Anthropic

Segui la procedura guidata di configurazione per registrare un federation issuer, creare un service account Anthropic e creare una federation rule nella Claude Console. Utilizza questi valori specifici per Google Cloud.

Federation issuer: Google pubblica il proprio documento di discovery OIDC pubblicamente, quindi utilizza 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_source": "discovery"
}

Federation rule: Effettua il match su entrambi i claim sub ed email. email è l'indirizzo leggibile del service account; sub è l'ID univoco numerico del service account, che Google non riutilizza mai, quindi vincolarlo protegge la rule se il service account viene eliminato e ne viene 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
}

Acquisire e utilizzare il token

All'interno del tuo workload Google Cloud, recupera il token di identità dal server di metadati, scambialo tramite POST /v1/oauth/token e utilizza il bearer token restituito per chiamare l'API di Claude. Ogni SDK di Anthropic gestisce per te lo scambio e il ciclo di refresh 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(message.content[0].text)

I token di identità di Google scadono dopo circa un'ora. Gli SDK richiamano automaticamente il token provider ed eseguono nuovamente lo scambio prima della scadenza. Per gli script shell che vengono eseguiti più a lungo del valore expires_in del token di accesso, esegui il refresh con un timer e ripeti lo scambio.

Verificare 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, aud sia https://api.anthropic.com ed email corrisponda al valore nella tua federation rule. Quindi esegui lo scambio dalla 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 fallito; la causa più comune lato Google Cloud è l'assenza del claim email (richiedi il token con format=full affinché venga incluso).

Limitare l'ambito della rule

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

• Corrispondenza esatta di sub: Imposta l'ID univoco numerico completo in claims.sub e non utilizzare mai subject_prefix per i token Google.
• Vincola il claim email: Aggiungi claims.email insieme a sub in modo che sia l'ID stabile sia l'indirizzo leggibile debbano corrispondere.
• Vincola l'audience: Imposta audience al valore esatto che richiedi dal server di metadati in modo che i token emessi per altri consumer vengano rifiutati.
• Vincola 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.

Passaggi successivi

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