WIF-Referenz

Diese Seite fasst die Konfigurationsoptionen, Validierungseinschränkungen und Fehlerzuordnungen für Workload Identity Federation zusammen. Schritt-für-Schritt-Anleitungen zur Einrichtung findest du in den Anbieter-Leitfäden.

Token-Exchange-Anfrage

POST /v1/oauth/token akzeptiert einen JSON-Body mit dem jwt-bearer-Grant gemäß RFC 7523. Das SDK erstellt diese Anfrage für dich aus den Umgebungsvariablen; die cURL-Beispiele in den einzelnen Anbieter-Leitfäden zeigen den rohen Body.

Token-Exchange-Antwort

POST /v1/oauth/token gibt eine standardmäßige OAuth-2.0-Token-Antwort zurück (RFC 6749 §5.1):

Umgebungsvariablen

Das SDK liest diese Variablen, um einen föderierten Token-Austausch ohne Konstruktorargumente durchzuführen.

Der direkte Federation-Pfad über Umgebungsvariablen wird nur aktiviert, wenn ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID und eine von ANTHROPIC_IDENTITY_TOKEN_FILE oder ANTHROPIC_IDENTITY_TOKEN alle gesetzt sind. ANTHROPIC_WORKSPACE_ID wird zusätzlich gelesen, steuert die Aktivierung aber nicht.

Rangfolge der Anmeldedaten

Das SDK löst Anmeldedaten in dieser Reihenfolge auf. Die erste Quelle, die Anmeldedaten liefert, gewinnt.

In der ant CLI rangieren die Einstellungen für Claude Models on Google Cloud (Anthropic managed) nach den Umgebungsvariablen für die Föderation und vor dem aktiven Profil. Die Einstellungen sind das Projekt, die Workspace-ID und der Standort. Du legst sie mit den --google-cloud-*-Flags oder den ANTHROPIC_GOOGLE_CLOUD_*-Variablen fest. Die CLI verwendet diese Einstellungen, sobald eine davon gesetzt ist. Mit diesen Einstellungen bezieht die CLI ihre Anmeldedaten aus den Google Application Default Credentials.

Wenn ein Profil geladen wird, füllen Umgebungsvariablen alle Felder, die das Profil auslässt, überschreiben aber niemals Felder, die das Profil explizit setzt. Beispielsweise füllt ANTHROPIC_WORKSPACE_ID das Feld workspace_id nur, wenn das aktive Profil es nicht setzt.

Profil-Konfigurationsdatei

Ein Profil ist eine benannte Konfigurationsdatei, die sowohl das SDK als auch die ant-CLI lesen. Mit Profilen kannst du Federation-Parameter mit deinem Container-Image ausliefern oder zwischen Umgebungen wechseln, ohne Code zu ändern.

Konfigurationsverzeichnis

Das SDK ermittelt das Konfigurationsverzeichnis in dieser Reihenfolge:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic unter Linux und macOS
3. %APPDATA%\Anthropic unter Windows

Aktives Profil

Der Name des aktiven Profils wird in dieser Reihenfolge aufgelöst:

1. $ANTHROPIC_PROFILE
2. Der Inhalt von <config_dir>/active_config (eine einzeilige Datei, die von ant profile activate <name> geschrieben wird)
3. Der Literalname default

Claude Code und das Claude Agent SDK berücksichtigen dieselbe Auflösungsreihenfolge, sodass ein hier konfiguriertes Federation-Profil auch diese Tools ohne zusätzliche Einrichtung authentifiziert.

Dateistruktur

Sowohl die Konfigurationsdatei als auch die Anmeldedatendatei enthalten ein String-Feld version auf oberster Ebene im Format major.minor (derzeit "1.0"). Das SDK schreibt dieses Feld automatisch, damit zukünftige Versionen ältere Formate erkennen und migrieren können; lass es weg, wenn du eine Konfiguration von Hand erstellst, und das SDK behandelt die Datei als aktuelle Version.

Beispiel für ein Federation-Profil

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Wenn authentication.identity_token weggelassen wird, greift das SDK auf ANTHROPIC_IDENTITY_TOKEN_FILE oder ANTHROPIC_IDENTITY_TOKEN aus der Umgebung zurück.

OAuth-Scopes

Der oauth_scope, den du für eine Federation-Regel festlegst, bestimmt, welche Claude API-Endpunkte das ausgestellte Access-Token aufrufen kann.

Eine Anfrage an einen Endpunkt außerhalb des Scopes des Tokens gibt HTTP 403 zurück. Feinere Scopes (pro Ressource oder Lesen versus Schreiben) sind derzeit nicht verfügbar.

Berechtigungsgrenzen

Der oauth_scope einer Federation-Regel ist eine Obergrenze: Das ausgestellte Token kann sie niemals überschreiten. Die organization_role (developer oder admin) des Ziel-Servicekontos bestimmt, welche Scopes gewährt werden können, daher muss eine Regel, die org:admin gewährt, auf ein Servicekonto mit organization_role=admin abzielen. Die effektiven Berechtigungen sind die Schnittmenge aus dem Scope der Regel und der Rolle des Servicekontos.

Validierungsregeln

Anthropic setzt diese Einschränkungen durch, wenn du Issuer und Regeln erstellst oder aktualisierst, sowie bei der Überprüfung eines eingehenden JWT zum Zeitpunkt des Austauschs.

Vollständige Parameterdetails und Antwortschemata findest du in der API-Referenz für Servicekonten, der API-Referenz für Federation-Issuer und der API-Referenz für Federation-Regeln.

Ressourcenfelder

URL-Felder

Die Felder issuer_url, jwks.discovery_base und jwks.url werden validiert:

URL-Validierungsfehler geben 400 invalid_request_error zurück, wobei der Feldname der Fehlermeldung vorangestellt ist (zum Beispiel issuer_url: url must use https scheme).

JWT-Überprüfung

Semantik des Regelabgleichs

Der match-Block einer Federation-Regel bestimmt, ob ein eingehendes JWT akzeptiert wird. Alle befüllten Felder werden mit UND-Semantik ausgewertet: Das JWT muss jeden befüllten Matcher erfüllen. Mindestens eines von subject_prefix, claims oder condition muss gesetzt sein; ein match-Block, der nur audience (oder gar keine Matcher) enthält, wird abgelehnt. Dies schützt vor Regeln, die jedes Token eines Issuers akzeptieren würden.

CEL-Auswertungsumgebung

Der condition-Ausdruck hat Zugriff auf eine einzige Variable:

Beispiel:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Fehler

Fehler beim Token-Austausch

POST /v1/oauth/token gibt Fehler im standardmäßigen API-Fehlerformat zurück. Das SDK meldet einen fehlgeschlagenen Austausch als WorkloadIdentityError, der den HTTP-Status und die Fehlerdetails aus dem Antwort-Body enthält. Die Request-ID befindet sich in Python, TypeScript und Ruby am Fehler und in Java in den Antwort-Headern der Exception. In Go ist sie nur in der Fehlermeldung enthalten, da sich der Typ des Fehlers in einem internen Paket befindet; die Fehler in C# und PHP enthalten sie nicht.

Jede Ablehnung einer Assertion gibt denselben undurchsichtigen 401 authentication_error mit der festen Meldung Authentication failed zurück, unabhängig davon, welche Prüfung fehlgeschlagen ist; ein unterscheidbarer Fehler würde es einem Aufrufer ermöglichen, die Regelkonfiguration auszuforschen. Der Ablehnungsgrund wird im Eintrag des Versuchs im Authentifizierungsverlauf in der Claude Console festgehalten, zum Beispiel match_subject_prefix, wenn der sub-Claim das subject_prefix der Regel nicht erfüllt, oder workspace_id_required, wenn die Regel mehrere Workspaces umfasst und die Anfrage keinen benennt. Anfragen, die abgelehnt werden, bevor die Organisation der Regel bestätigt ist (die oben genannte 400 invalid_request_error-Familie), hinterlassen keinen Verlaufseintrag; ihre Antwortnachrichten benennen das Problem direkt. Ein 401 ohne passenden Verlaufseintrag bedeutet in der Regel, dass die federation_rule_id selbst nicht erkannt wurde.

Häufige Fehler auf SDK-Seite

Fehlerbehebung bei einem fehlgeschlagenen Austausch

Eine 401 authentication_error-Antwort ist absichtlich undurchsichtig und ihre Meldung lautet immer Authentication failed; der Ablehnungsgrund wird im Authentifizierungsverlauf festgehalten, nicht in der Antwort.

Ein häufiger undurchsichtiger Fehler ist eine wiederverwendete Assertion: Eine Assertion mit einem jti-Claim kann nur einmal ausgetauscht werden, daher wird ein Workload, der dasselbe JWT erneut sendet (eine Wiederholungsschleife oder eine Aktualisierung, die ein nicht rotiertes Token erneut einliest), beim zweiten Austausch abgelehnt. Die Seite zum Authentifizierungsverlauf zeigt diese Versuche mit dem Grund jti_reused; die Lösung besteht darin, für jeden Austausch eine neue Assertion auszustellen.

Wenn du dennoch anhand des JWT selbst debuggen musst, arbeite diese Prüfungen der Reihe nach ab:

1. 1

   Das JWT dekodieren

   Dekodiere die gesendete Assertion, damit du jeden Claim mit deiner Issuer- und Regelkonfiguration vergleichen kannst:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Prüfen, ob iss mit dem Issuer übereinstimmt

   Der dekodierte iss-Claim muss Byte für Byte der registrierten issuer_url entsprechen, einschließlich Schema, Port und eines eventuellen abschließenden Schrägstrichs. Eine Abweichung bei einem einzigen Zeichen lässt die Überprüfung fehlschlagen.

3. 3

   Prüfen, ob aud mit der Regel übereinstimmt

   Der dekodierte aud-Claim muss den audience-Wert der Regel als exakte Übereinstimmung enthalten. Wenn aud ein Array ist, muss ein Element exakt übereinstimmen.

4. 4

   sub und jeden claims-Eintrag prüfen

   Vergleiche sub mit dem subject_prefix der Regel (Groß-/Kleinschreibung wird beachtet; ein abschließendes * ist ein Präfix-Abgleich, alles andere ist exakt). Vergleiche jeden Schlüssel in der claims-Map der Regel mit dem gleichnamigen Claim auf oberster Ebene.

5. 5

   exp, nbf und iat prüfen

   exp muss in der Zukunft liegen und nbf/iat müssen in der Vergangenheit liegen, innerhalb des 30-Sekunden-Toleranzfensters. Wenn die Uhr des Workload-Hosts abgewichen ist, wird ein ansonsten gültiges Token abgelehnt.

6. 6

   JWKS-Erreichbarkeit prüfen

   Rufe im discovery-Modus <jwks.discovery_base or issuer_url>/.well-known/openid-configuration über öffentliches HTTPS auf Port 443 ab und bestätige, dass jwks_uri aufgelöst wird. Rufe bei explicit_url die JWKS-URL direkt ab. Bestätige bei inline, dass der Signaturschlüssel des Issuers seit der Registrierung der Schlüssel nicht rotiert wurde.

   Wenn der Issuer seinen Signaturschlüssel rotiert und sofort damit zu signieren begonnen hat, können Austauschvorgänge bis zu einer Minute lang fehlschlagen, während der JWKS-Cache von Anthropic aktualisiert wird. Siehe Schlüsselrotation und Caching.

JWKS-Quellmodi

Wenn du einen Federation-Issuer registrierst, steuert das Feld jwks, wie Anthropic die öffentlichen Schlüssel bezieht, mit denen JWT-Signaturen dieses Issuers überprüft werden. Es handelt sich um eine diskriminierte Union mit type als Schlüssel:

Die diskriminierte Union macht die zugehörigen Felder konstruktionsbedingt gegenseitig ausschließend. Sowohl discovery als auch explicit_url akzeptieren zusätzlich einen optionalen ca_cert_pem-String für Issuer, die TLS über eine private CA bereitstellen.

Schlüsselrotation und Caching

In den Modi discovery und explicit_url speichert Anthropic das abgerufene JWKS im Cache. Wenn dein Identitätsanbieter einen neuen Signaturschlüssel veröffentlicht und sofort beginnt, Tokens damit zu signieren, können Austauschvorgänge mit diesen Tokens bis zu 1 Minute lang mit einem Signaturfehler fehlschlagen, während der Cache aktualisiert wird.

Um dieses Zeitfenster zu vermeiden, veröffentliche einen neuen Signaturschlüssel im JWKS mindestens 15 Minuten, bevor dein Identitätsanbieter beginnt, Tokens damit zu signieren, und behalte den abgelösten Schlüssel im JWKS, bis die damit signierten Tokens abgelaufen sind. Verwaltete Identitätsanbieter halten sich in der Regel von selbst an diese Vorgehensweise. Wenn du deinen eigenen Issuer betreibst (einen selbstverwalteten Kubernetes-Cluster, einen SPIRE-OIDC-Discovery-Provider oder einen benutzerdefinierten Okta-Autorisierungsserver mit konfiguriertem Rotationsrhythmus), stelle sicher, dass deine Rotationsrichtlinie neue Schlüssel vor ihrer ersten Verwendung veröffentlicht.