WIF-Referenz

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

Token-Austausch-Anfrage

POST /v1/oauth/token akzeptiert einen JSON-Body, der den jwt-bearer-Grant aus RFC 7523 verwendet. Die SDKs erstellen diese Anfrage für dich aus den Umgebungsvariablen; die cURL-Beispiele in jedem Anbieter-Leitfaden zeigen den rohen Body.

Token-Austausch-Antwort

POST /v1/oauth/token gibt eine Standard-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 aber nicht die Aktivierung.

Rangfolge der Anmeldedaten

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

Wenn ein Profil geladen wird, füllen Umgebungsvariablen alle Felder, die das Profil weglässt, überschreiben aber niemals Felder, die das Profil explizit setzt. Zum Beispiel 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 findet 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 literale Name default

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

Dateilayout

Sowohl die Konfigurationsdatei als auch die Anmeldedaten-Datei tragen ein String-Feld version auf oberster Ebene im Format major.minor (derzeit "1.0"). Das SDK schreibt dieses Feld automatisch, damit zukünftige Releases ä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, fällt das SDK auf ANTHROPIC_IDENTITY_TOKEN_FILE oder ANTHROPIC_IDENTITY_TOKEN aus der Umgebung zurück.

OAuth-Scopes

Der oauth_scope, den du auf einer Federation-Regel setzt, bestimmt, welche Claude-API-Endpunkte das ausgestellte Access-Token aufrufen kann.

Eine Anfrage an einen Endpunkt außerhalb des Token-Scopes 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 ihn niemals überschreiten. Die organization_role des Ziel-Service-Accounts (developer oder admin) bestimmt, welche Scopes gewährt werden können, sodass eine Regel, die org:admin gewährt, auf einen Service-Account mit organization_role=admin zielen muss. Die effektiven Berechtigungen sind die Schnittmenge aus dem Scope der Regel und der Rolle des Service-Accounts.

Validierungsregeln

Anthropic erzwingt diese Einschränkungen, wenn du Issuer und Regeln erstellst oder aktualisierst und wenn ein eingehendes JWT zum Zeitpunkt des Austauschs verifiziert wird.

Vollständige Parameterdetails und Antwortschemata findest du in der Service-Accounts-API-Referenz, der Federation-Issuers-API-Referenz und der Federation-Rules-API-Referenz.

Ressourcenfelder

URL-Felder

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

Fehler bei der URL-Validierung geben 400 invalid_request_error zurück, mit dem Feldnamen als Präfix der Fehlermeldung (zum Beispiel issuer_url: url must use https scheme).

JWT-Verifizierung

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

Token-Austausch-Fehler

POST /v1/oauth/token gibt Fehler in der standardmäßigen API-Fehlerform zurück. Das SDK verpackt Austauschfehler in einen typisierten FederationExchangeError (oder das sprachspezifische Äquivalent), der den HTTP-Status, den Antwort-Body und die request_id bereitstellt.

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 aufgezeichnet, 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 obige Familie 400 invalid_request_error), hinterlassen keinen Verlaufseintrag; ihre Antwortmeldungen benennen das Problem direkt. Ein 401 ohne passenden Verlaufseintrag bedeutet in der Regel, dass die federation_rule_id selbst nicht erkannt wurde.

Häufige SDK-seitige Fehler

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 aufgezeichnet, nicht in der Antwort.

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

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

1. 1

   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 in einem einzigen Zeichen lässt die Verifizierung 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-Abweichungsfensters. Wenn die Uhr des Workload-Hosts abgewichen ist, wird ein ansonsten gültiges Token abgelehnt.

6. 6

   JWKS-Erreichbarkeit prüfen

   Rufe im Modus discovery <jwks.discovery_base or issuer_url>/.well-known/openid-configuration über öffentliches HTTPS auf Port 443 ab und bestätige, dass jwks_uri auflöst. 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 Austausche 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, die zur Verifizierung von JWT-Signaturen dieses Issuers verwendet werden. Es ist eine diskriminierte Union mit type als Schlüssel:

Die diskriminierte Union macht die Begleitfelder konstruktionsbedingt gegenseitig ausschließend. Sowohl discovery als auch explicit_url akzeptieren zusätzlich einen optionalen String ca_cert_pem für Issuer, die TLS von einer privaten 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, Token damit zu signieren, können Austausche, die diese Token vorlegen, 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, Token damit zu signieren, und behalte den abgelösten Schlüssel im JWKS, bis die damit signierten Token abgelaufen sind. Verwaltete Identitätsanbieter befolgen diese Disziplin in der Regel von selbst. Wenn du deinen eigenen Issuer betreibst (einen selbstverwalteten Kubernetes-Cluster, einen SPIRE-OIDC-Discovery-Provider oder einen benutzerdefinierten Okta-Autorisierungsserver mit konfiguriertem Rotationsrhythmus), bestätige, dass deine Rotationsrichtlinie neue Schlüssel vor der ersten Verwendung veröffentlicht.