WIF mit Google Cloud verwenden

Jede Google Cloud-Compute-Umgebung mit Zugriff auf den Instanz-Metadatenserver (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE) und GKE mit Workload Identity) kann ein Google-signiertes „identity token“ (Identitätstoken) für ihr angehängtes Dienstkonto anfordern. Der Aussteller des Tokens ist https://accounts.google.com, und Anthropic kann es direkt über die standardmäßige OIDC-Discovery validieren, ohne dass eine zusätzliche Google Cloud-Konfiguration erforderlich ist.

Dieser Leitfaden zeigt, wie du den Google-Aussteller bei Anthropic registrierst, ein Google-Dienstkonto an ein Anthropic-Dienstkonto bindest und deinen Workload sein Identitätstoken gegen ein kurzlebiges Claude API-Zugriffstoken eintauschen lässt.

Voraussetzungen

• Vertrautheit mit den WIF-Konzepten: Dienstkonten, Föderationsaussteller und Föderationsregeln.
• Ein Google Cloud-Projekt mit einem Workload, der auf Cloud Run, Cloud Functions, App Engine, Compute Engine oder GKE läuft.
• Ein benutzerverwaltetes Google-Dienstkonto, das an diesen Workload angehängt ist (nicht das Compute Engine-Standarddienstkonto).
• Berechtigung zum Erstellen von Dienstkonten, Föderationsausstellern und Föderationsregeln in der Claude Console für deine Anthropic-Organisation.

Google Cloud konfigurieren

Google stellt Identitätstoken automatisch für jeden Workload mit einem angehängten Dienstkonto aus. Auf der Google-Seite muss nichts aktiviert werden, außer das richtige Dienstkonto anzuhängen, aber die Schritte unterscheiden sich geringfügig zwischen Standard-Compute und 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
}

Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die Kachel Google Cloud aus. Der Assistent führt dich durch die Registrierung des Ausstellers, das Erstellen eines Dienstkontos und das Erstellen einer Föderationsregel.

Der Assistent erstellt diese Ressourcen für dich. Verwende die folgenden Werte, unabhängig davon, ob du sie im Assistenten eingibst oder an die Admin API sendest:

Föderationsaussteller: Google veröffentlicht sein OIDC-Discovery-Dokument öffentlich, verwende daher den Discovery-Modus. Dieser einzelne Aussteller deckt jede Google Cloud-Oberfläche ab (Cloud Run, GCE, Cloud Functions, App Engine und GKE mit Workload Identity). Unterscheide Workloads mit Regeln, nicht mit Ausstellern.

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

Föderationsregel: Gleiche sowohl den sub- als auch den email-Claim ab. email ist die lesbare Dienstkontoadresse; sub ist die numerische eindeutige ID des Dienstkontos, die Google niemals wiederverwendet. Das Festlegen dieser ID schützt die Regel, falls das Dienstkonto gelöscht und später ein neues mit derselben E-Mail-Adresse erstellt wird. Finde die eindeutige ID mit 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
}

Token abrufen und verwenden

Rufe innerhalb deines Google Cloud-Workloads das Identitätstoken vom Metadatenserver ab, tausche es bei POST /v1/oauth/token ein und verwende das zurückgegebene Bearer-Token, um die Claude API aufzurufen. Jedes Anthropic SDK übernimmt den Austausch und die Aktualisierungsschleife für dich, wenn du ein Token-Provider-Callable bereitstellst, das ein frisches Identitätstoken vom Metadatenserver zurückgibt, wie in den folgenden Beispielen gezeigt.

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

Google-Identitätstoken laufen nach etwa einer Stunde ab. Die SDKs rufen den Token-Provider erneut auf und führen den Austausch vor Ablauf automatisch erneut durch. Bei Shell-Skripten, die länger laufen als das expires_in des Zugriffstokens, aktualisiere per Timer und wiederhole den Austausch.

Einrichtung überprüfen

Dekodiere innerhalb deines Workloads das Identitätstoken und bestätige, dass die Claims mit deiner Regel übereinstimmen:

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'

Prüfe, dass iss den Wert https://accounts.google.com hat, aud den Wert https://api.anthropic.com hat und email mit dem Wert in deiner Föderationsregel übereinstimmt. Führe dann den Austausch aus dem vorherigen Abschnitt aus. Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Wenn der Austausch mit der opaken 401-authentication_error-Antwort (Meldung Authentication failed) fehlschlägt, prüfe die Seite mit dem Authentifizierungsverlauf auf den Ablehnungsgrund und siehe Fehlerbehebung bei einem fehlgeschlagenen Austausch; die häufigste Ursache auf der Google Cloud-Seite ist ein fehlender email-Claim (fordere das Token mit format=full an, damit er enthalten ist).

Deine Regel eingrenzen

Beschränke den match-Block der Regel auf den engsten Geltungsbereich, der zu deinem Anwendungsfall passt:

• sub exakt abgleichen: Setze die vollständige numerische eindeutige ID in claims.sub und verwende niemals subject_prefix für Google-Token.
• Den email-Claim festlegen: Füge claims.email neben sub hinzu, sodass sowohl die stabile ID als auch die lesbare Adresse übereinstimmen müssen.
• Die Audience festlegen: Setze audience auf den exakten Wert, den du vom Metadatenserver anforderst, damit für andere Konsumenten ausgestellte Token abgelehnt werden.
• Das Projekt auf GKE festlegen: Füge für format=full-Token eine condition wie claims.google.compute_engine.project_id == "my-project" hinzu, um die Regel auf die Knoten eines Projekts zu beschränken.

Nächste Schritte

• Lies die Seite Workload Identity Federation für das vollständige Ressourcenmodell und die Rangfolge der SDK-Anmeldedaten.
• Füge pro Umgebung (Produktion, Staging) eine separate Föderationsregel hinzu, damit du eine widerrufen kannst, ohne die anderen zu beeinträchtigen.