AdminAuthentifizierung

WIF-Referenz

Umgebungsvariablen, Validierungsregeln, Profilkonfiguration und Fehlerreferenz für Workload Identity Federation.

Diese Seite fasst die Konfigurationsoberflächen, Validierungseinschränkungen und Fehlerzuordnungen für Workload Identity Federation zusammen. Für Einrichtungsanleitungen siehe die Provider-Leitfäden.

Token-Exchange-Anfrage

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

Feld	Erforderlich	Beschreibung
`grant_type`	Ja	Immer `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Ja	Das OIDC-JWT, das von deinem Identity Provider ausgestellt wurde.
`federation_rule_id`	Ja	Getaggte ID (`fdrl_...`) der auszuwertenden Federation-Regel.
`organization_id`	Ja	UUID deiner Anthropic-Organisation.
`service_account_id`	Ja	Getaggte ID (`svac_...`) des Ziel-Service-Accounts.
`workspace_id`	Bedingt	Getaggte ID (`wrkspc_...`) des Workspaces, auf den das ausgestellte Token beschränkt werden soll, oder das Literal `default` für den Standard-Workspace der Organisation. Erforderlich, wenn die Regel für mehr als einen Workspace aktiviert ist. Wenn weggelassen, wählt der Server den einzigen aktivierten Workspace der Regel aus.

Token-Exchange-Antwort

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

Feld	Typ	Beschreibung
`access_token`	string	Das kurzlebige Anthropic-Token mit dem Präfix `sk-ant-oat01-...`. Übergib es als `Authorization: Bearer <token>`.
`token_type`	string	Immer `Bearer`.
`expires_in`	integer	Sekunden bis zum Ablauf des Tokens.
`scope`	string	Der OAuth-Scope, der durch die passende Regel gewährt wurde.

Umgebungsvariablen

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

Variable	Erforderlich	Beschreibung	Beispiel
`ANTHROPIC_FEDERATION_RULE_ID`	Ja	Getaggte ID der auszuwertenden Federation-Regel.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Ja	UUID deiner Anthropic-Organisation. Du findest sie in der Claude Console unter Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Eine von `_TOKEN_FILE` oder `_TOKEN`	Dateisystempfad zum JWT, das von deinem Identity Provider (IdP) ausgestellt wurde. Das SDK liest diese Datei bei jedem Exchange neu ein, sodass projizierte Tokens, die auf der Festplatte rotieren, immer aktuell sind.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	Eine von `_TOKEN_FILE` oder `_TOKEN`	Das JWT als literaler String. Verwende dies, wenn deine Plattform das Token als Umgebungsvariable statt als Datei injiziert.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Ja	Getaggte ID des Ziel-Service-Accounts bei Anthropic, als der das ausgestellte Access-Token agiert.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Bedingt	Getaggte ID des Workspaces, auf den das ausgestellte Token beschränkt werden soll, oder das Literal `default`. Erforderlich, wenn die Federation-Regel für mehr als einen Workspace aktiviert ist; optional, wenn die Regel an einen einzelnen Workspace gebunden ist. Das ausgestellte Token wird zum Zeitpunkt des Exchange auf diesen Workspace beschränkt, sodass ein Wechsel des Workspaces einen neuen Exchange erfordert.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Nein	Name eines Konfigurationsprofils, das geladen werden soll. Hat Vorrang vor den Federation-Umgebungsvariablen in dieser Tabelle.	`staging-profile`

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 zusammen mit diesen gelesen, steuert aber nicht die Aktivierung.

Eine Variable, die auf einen leeren String gesetzt ist, belegt trotzdem ihren Platz in der Credential-Prioritätskette. Wenn ANTHROPIC_API_KEY="" exportiert ist, wählt das SDK den API-Key-Pfad mit einem leeren Key, anstatt zur Federation durchzufallen. Lösche ungenutzte Credential-Variablen, anstatt sie zu leeren.

Credential-Priorität

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

Reihenfolge	Quelle	Hinweise
1	Konstruktorargument (`api_key=`, `auth_token=`, `credentials=`)	Überschreibt immer alles andere.
2	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN`	Überschattet Federation vollständig. Lösche diese, wenn du von API-Keys migrierst.
3	`ANTHROPIC_PROFILE`	Lädt `<config_dir>/configs/<name>.json`. Ein fehlendes benanntes Profil ist ein Fehler, kein Fall-Through.
4	Federation-Umgebungsvariablen	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	Aktives Profil	Aufgelöst aus `<config_dir>/active_config`, mit Fallback auf ein Profil namens `default`.

Wenn ein Profil geladen wird, füllen Umgebungsvariablen alle Felder aus, die das Profil auslässt, überschreiben aber niemals Felder, die das Profil explizit setzt. Zum Beispiel füllt ANTHROPIC_WORKSPACE_ID nur dann workspace_id aus, 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. Profile ermöglichen es dir, Federation-Parameter mit deinem Container-Image auszuliefern oder zwischen Umgebungen zu wechseln, ohne Code zu ändern.

Konfigurationsverzeichnis

Das SDK ermittelt das Konfigurationsverzeichnis in dieser Reihenfolge:

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

Aktives Profil

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

$ANTHROPIC_PROFILE
Der Inhalt von <config_dir>/active_config (eine einzeilige Datei, die von ant profile activate <name> geschrieben wird)
Der literale Name default

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

Dateistruktur

Pfad	Inhalt	Sensibilität
`<config_dir>/configs/<profile>.json`	`version`, der `authentication`-Block, `organization_id`, `workspace_id` und `base_url`.	Nicht geheim. Kann sicher committet oder in ein Image eingebettet werden.
`<config_dir>/credentials/<profile>.json`	`version`, das gecachte `access_token`, `expires_at` und (für interaktives Login) `refresh_token`.	Geheim. Vom SDK mit Modus `0600` geschrieben.

Sowohl die Config-Datei als auch die Credentials-Datei enthalten 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; lässt du es beim manuellen Erstellen einer Config weg, behandelt das SDK die Datei als aktuelle Version.

Beispiel für ein Federation-Profil

configs/production.json

{
  "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.

Scope	Gewährt Zugriff auf
`workspace:developer`	Alle nicht-administrativen Claude-API-Endpunkte im Workspace der Regel: Messages (einschließlich Streaming und Token-Zählung), Models, Managed Agents und deren Sessions, Files und Skills. Dies entspricht dem Zugriff, den ein für denselben Workspace ausgestellter API-Key hat.
`org:manage_tunnels`	Die MCP-Tunnels-API: Tunnel auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnel archivieren. Das Create-Tunnel-Modal der Console sperrt diesen Scope, wenn du von dort aus eine Regel erstellst.

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

Validierungsregeln

Anthropic erzwingt diese Einschränkungen, wenn du Issuer und Regeln erstellst oder aktualisierst, sowie bei der Verifizierung eines eingehenden JWT zum Zeitpunkt des Exchange.

Ressourcenfelder

Feld	Einschränkung
`name` von Issuer, Regel und Service-Account	Muss `^[a-z0-9-]+$` entsprechen, Länge 1 bis 255 Zeichen.
`workspace_id`	Optional. Der Workspace (`wrkspc_...`), dessen Kontingent, Abrechnung und Ratenlimits für Tokens gelten, die unter dieser Regel ausgestellt werden. Muss ein Workspace in derselben Organisation sein, und der Ziel-Service-Account muss Mitglied dieses Workspaces sein. Kann für Regeln weggelassen werden, die nur für einen Workspace konfiguriert sind.
`token_lifetime_seconds`	Integer zwischen `60` und `86400` (1 Minute bis 24 Stunden). Standard `3600`. Werte außerhalb dieses Bereichs werden zum Zeitpunkt der Anfrage abgelehnt. Siehe Token-Lebensdauer und Refresh.

URL-Felder

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

Einschränkung	Detail
Schema	Muss `https` sein.
Port	Muss `443` sein (explizit oder Standard).
Host	Muss ein öffentlicher DNS-Hostname für deinen OIDC-Provider sein. Muss zu öffentlichen IP-Adressen auflösen; IP-Literale werden nicht akzeptiert.

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

URL-Einschränkungen gelten nur für URLs, die Anthropic aufruft. In den JWKS-Modi explicit_url und inline sowie im discovery-Modus, wenn jwks.discovery_base gesetzt ist, wird die issuer_url als String mit dem JWT-iss-Claim verglichen und niemals abgerufen, sodass sie auf einen internen Hostnamen oder einen nicht standardmäßigen Port verweisen darf.

JWT-Verifizierung

Einschränkung	Detail
Maximale Größe	Das `assertion`-JWT darf höchstens 16 KiB groß sein.
Signaturalgorithmus	Nur asymmetrische Algorithmen (RSA- und ECDSA-Familien: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512) werden akzeptiert. HMAC (`HS256`, `HS384`, `HS512`) und `none` werden abgelehnt.
Key-ID	Der JWT-Header muss eine `kid` enthalten, die mit einem Key im JWKS des Issuers übereinstimmt. Tokens ohne `kid` werden abgelehnt.
Erforderliche Claims	`sub` muss vorhanden sein. `iat` muss vorhanden sein und darf nicht in der Zukunft liegen. `exp` muss vorhanden sein und in der Zukunft liegen.
Maximale Lebensdauer	Die Lebensdauer des Tokens (`exp` minus `iat`) darf das konfigurierte Maximum des Issuers nicht überschreiten (standardmäßig 1 Stunde, für jeden Issuer in der Claude Console konfigurierbar).
Clock-Skew	Eine Toleranz von 30 Sekunden wird auf `exp`, `nbf` und `iat` angewendet.

Regel-Matching-Semantik

Der match-Block einer Federation-Regel bestimmt, ob ein eingehendes JWT akzeptiert wird. Alle ausgefüllten Felder werden mit AND-Semantik ausgewertet: Das JWT muss jeden ausgefü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 von einem Issuer akzeptieren würden.

Matcher	Typ	Semantik
`subject_prefix`	string	Exakter Abgleich mit dem JWT-`sub`-Claim. Ein abschließendes `` macht daraus einen Präfix-Abgleich (der `sub`-Wert muss mit den Zeichen vor dem `` beginnen). Case-sensitive.
`audience`	string	Der JWT-`aud`-Claim muss genau diesen String enthalten. Wenn `aud` ein Array ist, erfüllt jedes exakt übereinstimmende Element die Prüfung.
`claims`	map<string, string>	Jeder Key ist ein Claim-Name auf oberster Ebene und jeder Wert ist der erforderliche exakte String-Wert. Für verschachtelte, numerische, boolesche oder komplexe Claims wie Listen und Maps verwende stattdessen `condition` mit einem CEL-Ausdruck.
`condition`	string (CEL)	Ein CEL-Ausdruck, der zu `true` auswerten muss.

CEL-Auswertungsumgebung

Der condition-Ausdruck hat Zugriff auf eine einzige Variable:

Variable	Typ	Inhalt
`claims`	map	Der vollständige dekodierte JWT-Claim-Satz. Verschachtelte Objekte sind als verschachtelte Maps zugänglich.

Beispiel:

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

CEL-Bedingungen sind Sicherheitsgrenzen. Ein Ausdruck, der für mehr Eingaben als beabsichtigt zu true auswertet, gewährt breiteren Zugriff als beabsichtigt. Bevorzuge die statischen Matcher, wenn sie deine Einschränkung ausdrücken können.

Fehler

Token-Exchange-Fehler

POST /v1/oauth/token gibt Fehler im standardmäßigen API-Fehlerformat zurück. Das SDK verpackt Exchange-Fehler in einen typisierten FederationExchangeError (oder das sprachspezifische Äquivalent), der den HTTP-Status, den Response-Body und die request_id verfügbar macht.

Status	Fehler	Ursache	Lösung
400	`invalid_request`	`federation_rule_id` ist fehlerhaft oder ein erforderliches Anfragefeld fehlt.	Überprüfe die `fdrl_`-ID und dass der Request-Body alle erforderlichen Felder enthält.
400	`invalid_request`	`workspace_id_required`: Die Federation-Regel ist für mehr als einen Workspace aktiviert und die Anfrage lässt `workspace_id` weg.	Setze `ANTHROPIC_WORKSPACE_ID` (oder das `workspace_id`-Body-Feld bei einer rohen Anfrage) auf die `wrkspc_...`-ID, auf die das Token beschränkt werden soll. Siehe Token-Exchange-Anfrage.
400	`invalid_grant`	Der JWT-`iss`-Claim entspricht nicht exakt der registrierten `issuer_url`.	Vergleiche Byte für Byte, einschließlich abschließender Schrägstriche und Schema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	JWKS-Abruf fehlgeschlagen, JWKS ist veraltet, oder das JWT wurde mit einem Key signiert, der nicht im JWKS enthalten ist.	Für den `inline`-Modus aktualisiere den Issuer mit den rotierten Keys. Für `discovery` und `explicit_url` bestätige, dass der JWKS-Endpunkt auf Port 443 erreichbar ist; wenn der Issuer kürzlich seinen Signatur-Key rotiert hat, siehe Key-Rotation und Caching.
400	`invalid_grant`	Der JWT-`exp`-Claim liegt in der Vergangenheit (außerhalb des 30-Sekunden-Skew-Fensters).	Bestätige, dass dein Identity Provider ein frisches Token projiziert und das SDK die Token-Datei neu einliest.
400	`invalid_grant`	Das JWT wurde verifiziert, aber seine Claims erfüllen den `match`-Block der Regel nicht.	Dekodiere das JWT und vergleiche jeden Claim mit der Regel. `subject_prefix` ist case-sensitive. `audience` erfordert einen exakten Element-Abgleich.
400	`invalid_grant`	Die `federation_rule_id` existiert nicht, ist archiviert, oder das JWT ist nicht dafür autorisiert (konsolidiert, um Enumeration zu verhindern).	Bestätige die Regel-ID in der Claude Console und dass die Regel nicht archiviert wurde.

Alle invalid_grant-Fehler geben HTTP 400 zurück; die spezifische Ursache wird nur serverseitig protokolliert und nicht in der Antwort offengelegt.

Häufige SDK-seitige Fehler

Symptom	Ursache	Lösung
SDK meldet „no credentials" statt einen Exchange durchzuführen	Eine von `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` oder `ANTHROPIC_IDENTITY_TOKEN[_FILE]` ist nicht gesetzt und kein Profil ist aktiv.	Setze alle vier Variablen oder konfiguriere ein Profil.
SDK authentifiziert mit einem API-Key statt zu föderieren	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` ist gesetzt und gewinnt die Priorität.	Lösche die Key- oder Token-Variable.
`FileNotFoundError` bei der ersten Anfrage	Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei lazy zum Zeitpunkt des Exchange.	Bestätige, dass das Projected-Token-Volume gemountet ist und der Pfad übereinstimmt.
Token-Exchange erfolgreich, aber eine Claude-API-Anfrage gibt 403 zurück	Der Scope des ausgestellten Tokens gewährt keinen Zugriff auf diesen Endpunkt.	Überprüfe den `oauth_scope` der Regel anhand von OAuth-Scopes.
Authentifizierung schlägt mit leerem Credential fehl	Eine Credential-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte gewinnen trotzdem ihren Prioritätsplatz.	Lösche die Variable mit `unset VAR` statt `VAR=""`.

Fehlerbehebung bei einem fehlgeschlagenen Exchange

Eine 400 invalid_grant-Antwort ist absichtlich undurchsichtig; die spezifische Ursache wird nur serverseitig protokolliert.

Beginne mit der Authentifizierungsverlaufsseite in der Claude Console. Kürzliche Exchange-Versuche zeigen den Issuer und die Regel, die ausgewertet wurden, die JWT-Claims, die geprüft wurden, und welcher Validierungsschritt fehlgeschlagen ist – das erspart dir in der Regel die folgenden Prüfungen.

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

Dekodiere das JWT
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"
Prüfe, ob iss mit dem Issuer übereinstimmt
Der dekodierte iss-Claim muss Byte für Byte mit der registrierten issuer_url übereinstimmen, einschließlich Schema, Port und eventuellem abschließenden Schrägstrich. Eine Abweichung bei einem einzigen Zeichen lässt die Verifizierung fehlschlagen.
Prüfe, 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.
Prüfe sub und jeden claims-Eintrag
Vergleiche sub mit dem subject_prefix der Regel (case-sensitive; ein abschließendes * ist ein Präfix-Abgleich, alles andere ist exakt). Vergleiche jeden Key in der claims-Map der Regel mit dem gleichnamigen Claim auf oberster Ebene.
Prüfe exp, nbf und iat
exp muss in der Zukunft liegen und nbf/iat müssen in der Vergangenheit liegen, innerhalb des 30-Sekunden-Skew-Fensters. Wenn die Uhr des Workload-Hosts abgedriftet ist, wird ein ansonsten gültiges Token abgelehnt.
Prüfe die JWKS-Erreichbarkeit
Für den discovery-Modus rufe <jwks.discovery_base oder issuer_url>/.well-known/openid-configuration über öffentliches HTTPS auf Port 443 ab und bestätige, dass jwks_uri auflöst. Für explicit_url rufe die JWKS-URL direkt ab. Für inline bestätige, dass der Signatur-Key des Issuers seit der Registrierung der Keys nicht rotiert wurde.
Wenn der Issuer seinen Signatur-Key rotiert hat und sofort damit zu signieren begonnen hat, können Exchanges bis zu einer Minute lang fehlschlagen, während der JWKS-Cache von Anthropic aktualisiert wird. Siehe Key-Rotation und Caching.

JWKS-Quellmodi

Wenn du einen Federation-Issuer registrierst, steuert das jwks-Feld, wie Anthropic die öffentlichen Keys erhält, die zur Verifizierung von JWT-Signaturen dieses Issuers verwendet werden. Es ist eine Discriminated Union mit type als Schlüssel:

`jwks.type`	`jwks`-Struktur	Verhalten	Verwende, wenn
`discovery` (Standard)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` ist optional; setze es, wenn die Discovery-URL von `issuer_url` abweicht)	Anthropic ruft `<discovery_base oder issuer_url>/.well-known/openid-configuration` ab, liest `jwks_uri` aus dem Discovery-Dokument und ruft das JWKS von dort ab.	Dein IdP stellt ein standardmäßiges OIDC-Discovery-Dokument im öffentlichen Internet bereit. Die meisten verwalteten Provider (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) unterstützen dies.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic ruft das JWKS direkt von `url` ab. Die `issuer_url` wird nur für den String-Vergleich mit dem JWT-`iss`-Claim verwendet und niemals aufgerufen.	Dein IdP stellt kein Discovery-Dokument bereit, oder Discovery ist nur intern verfügbar, aber das JWKS ist öffentlich erreichbar.
`inline`	`{ "type": "inline", "keys": [...] }`	Du lieferst das Array von JWK-Objekten inline (das `keys`-Array aus dem JWKS-Dokument, nicht das Wrapper-Objekt). Anthropic stellt keine ausgehende Anfrage. Die `issuer_url` wird nur für den `iss`-Vergleich verwendet.	Air-Gapped-Umgebungen, selbstverwaltete Kubernetes-Cluster mit cluster-internen Issuer-URLs, oder wenn du explizite Kontrolle über die Key-Rotation haben möchtest.

Die Discriminated Union macht die Begleitfelder per Konstruktion gegenseitig ausschließend. Sowohl discovery als auch explicit_url akzeptieren zusätzlich einen optionalen ca_cert_pem-String für Issuer, die TLS von einer privaten CA bereitstellen.

Key-Rotation und Caching

In den Modi discovery und explicit_url cacht Anthropic das abgerufene JWKS. Wenn dein Identity Provider einen neuen Signatur-Key veröffentlicht und sofort beginnt, Tokens damit zu signieren, können Exchanges, die diese Tokens präsentieren, bis zu einer Minute lang mit einem Signaturfehler fehlschlagen, während der Cache aktualisiert wird.

Um dieses Zeitfenster zu vermeiden, veröffentliche einen neuen Signatur-Key mindestens 15 Minuten im JWKS, bevor dein Identity Provider beginnt, Tokens damit zu signieren, und behalte den abgelösten Key im JWKS, bis die damit signierten Tokens abgelaufen sind. Verwaltete Identity Provider folgen dieser Disziplin in der Regel von selbst. Wenn du deinen eigenen Issuer betreibst (einen selbstverwalteten Kubernetes-Cluster, einen SPIRE-OIDC-Discovery-Provider oder einen Okta-Custom-Authorization-Server mit konfigurierter Rotationskadenz), bestätige, dass deine Rotationsrichtlinie neue Keys vor der ersten Verwendung veröffentlicht.

Im inline-Modus gibt es keine automatische Key-Aktualisierung. Wenn dein Identity Provider seine Signatur-Keys rotiert, musst du die Issuer-Konfiguration mit dem neuen JWKS aktualisieren, sonst schlagen alle Token-Exchanges bei der Signaturverifizierung fehl.

Was this page helpful?

AdminAuthentifizierung

WIF-Referenz

Umgebungsvariablen, Validierungsregeln, Profilkonfiguration und Fehlerreferenz für Workload Identity Federation.

Token-Exchange-Anfrage

Feld	Erforderlich	Beschreibung
`grant_type`	Ja	Immer `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Ja	Das OIDC-JWT, das von deinem Identity Provider ausgestellt wurde.
`federation_rule_id`	Ja	Getaggte ID (`fdrl_...`) der auszuwertenden Federation-Regel.
`organization_id`	Ja	UUID deiner Anthropic-Organisation.
`service_account_id`	Ja	Getaggte ID (`svac_...`) des Ziel-Service-Accounts.
`workspace_id`	Bedingt	Getaggte ID (`wrkspc_...`) des Workspaces, auf den das ausgestellte Token beschränkt werden soll, oder das Literal `default` für den Standard-Workspace der Organisation. Erforderlich, wenn die Regel für mehr als einen Workspace aktiviert ist. Wenn weggelassen, wählt der Server den einzigen aktivierten Workspace der Regel aus.

Token-Exchange-Antwort

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

Feld	Typ	Beschreibung
`access_token`	string	Das kurzlebige Anthropic-Token mit dem Präfix `sk-ant-oat01-...`. Übergib es als `Authorization: Bearer <token>`.
`token_type`	string	Immer `Bearer`.
`expires_in`	integer	Sekunden bis zum Ablauf des Tokens.
`scope`	string	Der OAuth-Scope, der durch die passende Regel gewährt wurde.

Umgebungsvariablen

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

Variable	Erforderlich	Beschreibung	Beispiel
`ANTHROPIC_FEDERATION_RULE_ID`	Ja	Getaggte ID der auszuwertenden Federation-Regel.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Ja	UUID deiner Anthropic-Organisation. Du findest sie in der Claude Console unter Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Eine von `_TOKEN_FILE` oder `_TOKEN`	Dateisystempfad zum JWT, das von deinem Identity Provider (IdP) ausgestellt wurde. Das SDK liest diese Datei bei jedem Exchange neu ein, sodass projizierte Tokens, die auf der Festplatte rotieren, immer aktuell sind.	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	Eine von `_TOKEN_FILE` oder `_TOKEN`	Das JWT als literaler String. Verwende dies, wenn deine Plattform das Token als Umgebungsvariable statt als Datei injiziert.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Ja	Getaggte ID des Ziel-Service-Accounts bei Anthropic, als der das ausgestellte Access-Token agiert.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Bedingt	Getaggte ID des Workspaces, auf den das ausgestellte Token beschränkt werden soll, oder das Literal `default`. Erforderlich, wenn die Federation-Regel für mehr als einen Workspace aktiviert ist; optional, wenn die Regel an einen einzelnen Workspace gebunden ist. Das ausgestellte Token wird zum Zeitpunkt des Exchange auf diesen Workspace beschränkt, sodass ein Wechsel des Workspaces einen neuen Exchange erfordert.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Nein	Name eines Konfigurationsprofils, das geladen werden soll. Hat Vorrang vor den Federation-Umgebungsvariablen in dieser Tabelle.	`staging-profile`

Credential-Priorität

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

Reihenfolge	Quelle	Hinweise
1	Konstruktorargument (`api_key=`, `auth_token=`, `credentials=`)	Überschreibt immer alles andere.
2	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN`	Überschattet Federation vollständig. Lösche diese, wenn du von API-Keys migrierst.
3	`ANTHROPIC_PROFILE`	Lädt `<config_dir>/configs/<name>.json`. Ein fehlendes benanntes Profil ist ein Fehler, kein Fall-Through.
4	Federation-Umgebungsvariablen	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	Aktives Profil	Aufgelöst aus `<config_dir>/active_config`, mit Fallback auf ein Profil namens `default`.

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Das SDK ermittelt das Konfigurationsverzeichnis in dieser Reihenfolge:

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

Aktives Profil

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

$ANTHROPIC_PROFILE
Der Inhalt von <config_dir>/active_config (eine einzeilige Datei, die von ant profile activate <name> geschrieben wird)
Der literale Name default

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

Dateistruktur

Pfad	Inhalt	Sensibilität
`<config_dir>/configs/<profile>.json`	`version`, der `authentication`-Block, `organization_id`, `workspace_id` und `base_url`.	Nicht geheim. Kann sicher committet oder in ein Image eingebettet werden.
`<config_dir>/credentials/<profile>.json`	`version`, das gecachte `access_token`, `expires_at` und (für interaktives Login) `refresh_token`.	Geheim. Vom SDK mit Modus `0600` geschrieben.

Beispiel für ein Federation-Profil

configs/production.json

{
  "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.

Scope	Gewährt Zugriff auf
`workspace:developer`	Alle nicht-administrativen Claude-API-Endpunkte im Workspace der Regel: Messages (einschließlich Streaming und Token-Zählung), Models, Managed Agents und deren Sessions, Files und Skills. Dies entspricht dem Zugriff, den ein für denselben Workspace ausgestellter API-Key hat.
`org:manage_tunnels`	Die MCP-Tunnels-API: Tunnel auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnel archivieren. Das Create-Tunnel-Modal der Console sperrt diesen Scope, wenn du von dort aus eine Regel erstellst.

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

Validierungsregeln

Anthropic erzwingt diese Einschränkungen, wenn du Issuer und Regeln erstellst oder aktualisierst, sowie bei der Verifizierung eines eingehenden JWT zum Zeitpunkt des Exchange.

Ressourcenfelder

Feld	Einschränkung
`name` von Issuer, Regel und Service-Account	Muss `^[a-z0-9-]+$` entsprechen, Länge 1 bis 255 Zeichen.
`workspace_id`	Optional. Der Workspace (`wrkspc_...`), dessen Kontingent, Abrechnung und Ratenlimits für Tokens gelten, die unter dieser Regel ausgestellt werden. Muss ein Workspace in derselben Organisation sein, und der Ziel-Service-Account muss Mitglied dieses Workspaces sein. Kann für Regeln weggelassen werden, die nur für einen Workspace konfiguriert sind.
`token_lifetime_seconds`	Integer zwischen `60` und `86400` (1 Minute bis 24 Stunden). Standard `3600`. Werte außerhalb dieses Bereichs werden zum Zeitpunkt der Anfrage abgelehnt. Siehe Token-Lebensdauer und Refresh.

URL-Felder

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

Einschränkung	Detail
Schema	Muss `https` sein.
Port	Muss `443` sein (explizit oder Standard).
Host	Muss ein öffentlicher DNS-Hostname für deinen OIDC-Provider sein. Muss zu öffentlichen IP-Adressen auflösen; IP-Literale werden nicht akzeptiert.

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

JWT-Verifizierung

Einschränkung	Detail
Maximale Größe	Das `assertion`-JWT darf höchstens 16 KiB groß sein.
Signaturalgorithmus	Nur asymmetrische Algorithmen (RSA- und ECDSA-Familien: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512) werden akzeptiert. HMAC (`HS256`, `HS384`, `HS512`) und `none` werden abgelehnt.
Key-ID	Der JWT-Header muss eine `kid` enthalten, die mit einem Key im JWKS des Issuers übereinstimmt. Tokens ohne `kid` werden abgelehnt.
Erforderliche Claims	`sub` muss vorhanden sein. `iat` muss vorhanden sein und darf nicht in der Zukunft liegen. `exp` muss vorhanden sein und in der Zukunft liegen.
Maximale Lebensdauer	Die Lebensdauer des Tokens (`exp` minus `iat`) darf das konfigurierte Maximum des Issuers nicht überschreiten (standardmäßig 1 Stunde, für jeden Issuer in der Claude Console konfigurierbar).
Clock-Skew	Eine Toleranz von 30 Sekunden wird auf `exp`, `nbf` und `iat` angewendet.

Regel-Matching-Semantik

Matcher	Typ	Semantik
`subject_prefix`	string	Exakter Abgleich mit dem JWT-`sub`-Claim. Ein abschließendes `` macht daraus einen Präfix-Abgleich (der `sub`-Wert muss mit den Zeichen vor dem `` beginnen). Case-sensitive.
`audience`	string	Der JWT-`aud`-Claim muss genau diesen String enthalten. Wenn `aud` ein Array ist, erfüllt jedes exakt übereinstimmende Element die Prüfung.
`claims`	map<string, string>	Jeder Key ist ein Claim-Name auf oberster Ebene und jeder Wert ist der erforderliche exakte String-Wert. Für verschachtelte, numerische, boolesche oder komplexe Claims wie Listen und Maps verwende stattdessen `condition` mit einem CEL-Ausdruck.
`condition`	string (CEL)	Ein CEL-Ausdruck, der zu `true` auswerten muss.

CEL-Auswertungsumgebung

Der condition-Ausdruck hat Zugriff auf eine einzige Variable:

Variable	Typ	Inhalt
`claims`	map	Der vollständige dekodierte JWT-Claim-Satz. Verschachtelte Objekte sind als verschachtelte Maps zugänglich.

Beispiel:

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

Fehler

Token-Exchange-Fehler

Status	Fehler	Ursache	Lösung
400	`invalid_request`	`federation_rule_id` ist fehlerhaft oder ein erforderliches Anfragefeld fehlt.	Überprüfe die `fdrl_`-ID und dass der Request-Body alle erforderlichen Felder enthält.
400	`invalid_request`	`workspace_id_required`: Die Federation-Regel ist für mehr als einen Workspace aktiviert und die Anfrage lässt `workspace_id` weg.	Setze `ANTHROPIC_WORKSPACE_ID` (oder das `workspace_id`-Body-Feld bei einer rohen Anfrage) auf die `wrkspc_...`-ID, auf die das Token beschränkt werden soll. Siehe Token-Exchange-Anfrage.
400	`invalid_grant`	Der JWT-`iss`-Claim entspricht nicht exakt der registrierten `issuer_url`.	Vergleiche Byte für Byte, einschließlich abschließender Schrägstriche und Schema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	JWKS-Abruf fehlgeschlagen, JWKS ist veraltet, oder das JWT wurde mit einem Key signiert, der nicht im JWKS enthalten ist.	Für den `inline`-Modus aktualisiere den Issuer mit den rotierten Keys. Für `discovery` und `explicit_url` bestätige, dass der JWKS-Endpunkt auf Port 443 erreichbar ist; wenn der Issuer kürzlich seinen Signatur-Key rotiert hat, siehe Key-Rotation und Caching.
400	`invalid_grant`	Der JWT-`exp`-Claim liegt in der Vergangenheit (außerhalb des 30-Sekunden-Skew-Fensters).	Bestätige, dass dein Identity Provider ein frisches Token projiziert und das SDK die Token-Datei neu einliest.
400	`invalid_grant`	Das JWT wurde verifiziert, aber seine Claims erfüllen den `match`-Block der Regel nicht.	Dekodiere das JWT und vergleiche jeden Claim mit der Regel. `subject_prefix` ist case-sensitive. `audience` erfordert einen exakten Element-Abgleich.
400	`invalid_grant`	Die `federation_rule_id` existiert nicht, ist archiviert, oder das JWT ist nicht dafür autorisiert (konsolidiert, um Enumeration zu verhindern).	Bestätige die Regel-ID in der Claude Console und dass die Regel nicht archiviert wurde.

Alle invalid_grant-Fehler geben HTTP 400 zurück; die spezifische Ursache wird nur serverseitig protokolliert und nicht in der Antwort offengelegt.

Häufige SDK-seitige Fehler

Symptom	Ursache	Lösung
SDK meldet „no credentials" statt einen Exchange durchzuführen	Eine von `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` oder `ANTHROPIC_IDENTITY_TOKEN[_FILE]` ist nicht gesetzt und kein Profil ist aktiv.	Setze alle vier Variablen oder konfiguriere ein Profil.
SDK authentifiziert mit einem API-Key statt zu föderieren	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` ist gesetzt und gewinnt die Priorität.	Lösche die Key- oder Token-Variable.
`FileNotFoundError` bei der ersten Anfrage	Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei lazy zum Zeitpunkt des Exchange.	Bestätige, dass das Projected-Token-Volume gemountet ist und der Pfad übereinstimmt.
Token-Exchange erfolgreich, aber eine Claude-API-Anfrage gibt 403 zurück	Der Scope des ausgestellten Tokens gewährt keinen Zugriff auf diesen Endpunkt.	Überprüfe den `oauth_scope` der Regel anhand von OAuth-Scopes.
Authentifizierung schlägt mit leerem Credential fehl	Eine Credential-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte gewinnen trotzdem ihren Prioritätsplatz.	Lösche die Variable mit `unset VAR` statt `VAR=""`.

Fehlerbehebung bei einem fehlgeschlagenen Exchange

Eine 400 invalid_grant-Antwort ist absichtlich undurchsichtig; die spezifische Ursache wird nur serverseitig protokolliert.

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

Dekodiere das JWT
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"
Prüfe, ob iss mit dem Issuer übereinstimmt
Der dekodierte iss-Claim muss Byte für Byte mit der registrierten issuer_url übereinstimmen, einschließlich Schema, Port und eventuellem abschließenden Schrägstrich. Eine Abweichung bei einem einzigen Zeichen lässt die Verifizierung fehlschlagen.
Prüfe, 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.
Prüfe sub und jeden claims-Eintrag
Vergleiche sub mit dem subject_prefix der Regel (case-sensitive; ein abschließendes * ist ein Präfix-Abgleich, alles andere ist exakt). Vergleiche jeden Key in der claims-Map der Regel mit dem gleichnamigen Claim auf oberster Ebene.
Prüfe exp, nbf und iat
exp muss in der Zukunft liegen und nbf/iat müssen in der Vergangenheit liegen, innerhalb des 30-Sekunden-Skew-Fensters. Wenn die Uhr des Workload-Hosts abgedriftet ist, wird ein ansonsten gültiges Token abgelehnt.
Prüfe die JWKS-Erreichbarkeit
Für den discovery-Modus rufe <jwks.discovery_base oder issuer_url>/.well-known/openid-configuration über öffentliches HTTPS auf Port 443 ab und bestätige, dass jwks_uri auflöst. Für explicit_url rufe die JWKS-URL direkt ab. Für inline bestätige, dass der Signatur-Key des Issuers seit der Registrierung der Keys nicht rotiert wurde.
Wenn der Issuer seinen Signatur-Key rotiert hat und sofort damit zu signieren begonnen hat, können Exchanges bis zu einer Minute lang fehlschlagen, während der JWKS-Cache von Anthropic aktualisiert wird. Siehe Key-Rotation und Caching.

JWKS-Quellmodi

`jwks.type`	`jwks`-Struktur	Verhalten	Verwende, wenn
`discovery` (Standard)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` ist optional; setze es, wenn die Discovery-URL von `issuer_url` abweicht)	Anthropic ruft `<discovery_base oder issuer_url>/.well-known/openid-configuration` ab, liest `jwks_uri` aus dem Discovery-Dokument und ruft das JWKS von dort ab.	Dein IdP stellt ein standardmäßiges OIDC-Discovery-Dokument im öffentlichen Internet bereit. Die meisten verwalteten Provider (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) unterstützen dies.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic ruft das JWKS direkt von `url` ab. Die `issuer_url` wird nur für den String-Vergleich mit dem JWT-`iss`-Claim verwendet und niemals aufgerufen.	Dein IdP stellt kein Discovery-Dokument bereit, oder Discovery ist nur intern verfügbar, aber das JWKS ist öffentlich erreichbar.
`inline`	`{ "type": "inline", "keys": [...] }`	Du lieferst das Array von JWK-Objekten inline (das `keys`-Array aus dem JWKS-Dokument, nicht das Wrapper-Objekt). Anthropic stellt keine ausgehende Anfrage. Die `issuer_url` wird nur für den `iss`-Vergleich verwendet.	Air-Gapped-Umgebungen, selbstverwaltete Kubernetes-Cluster mit cluster-internen Issuer-URLs, oder wenn du explizite Kontrolle über die Key-Rotation haben möchtest.

Key-Rotation und Caching

Was this page helpful?