AdminAuthentifizierung

WIF-Referenz

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

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

Token-Exchange-Anfrage

POST /v1/oauth/token akzeptiert einen JSON-Body unter Verwendung des RFC 7523 jwt-bearer-Grants. Die SDKs erstellen diese Anfrage für dich aus den Umgebungsvariablen; die cURL-Beispiele in jedem Provider-Leitfaden zeigen den rohen Body.

Feld	Erforderlich	Beschreibung
`grant_type`	Ja	Immer `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Ja	Das von deinem Identity Provider ausgestellte OIDC-JWT.
`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 Workspace, 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 von der übereinstimmenden Regel gewährte OAuth-Scope.

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`	Eines 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`	Eines von `_TOKEN_FILE` oder `_TOKEN`	Das wörtliche JWT als String. Verwende dies, wenn deine Plattform das Token als Umgebungsvariable statt als Datei injiziert.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Ja	Getaggte ID des Ziel-Anthropic-Service-Accounts, als der das ausgestellte Access-Token agiert.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Bedingt	Getaggte ID des Workspace, 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 Workspace-Wechsel einen neuen Exchange erfordert.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Nein	Name eines zu ladenden Konfigurationsprofils. 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 eines von ANTHROPIC_IDENTITY_TOKEN_FILE oder ANTHROPIC_IDENTITY_TOKEN alle gesetzt sind. ANTHROPIC_WORKSPACE_ID wird mitgelesen, ist aber keine Voraussetzung für die Aktivierung.

Eine Variable, die auf einen leeren String gesetzt ist, belegt weiterhin ihren Platz in der Credential-Vorrangkette. Wenn ANTHROPIC_API_KEY="" exportiert ist, wählt das SDK den API-Key-Pfad mit einem leeren Key, anstatt auf Federation zurückzufallen. Entferne ungenutzte Credential-Variablen, anstatt sie zu leeren.

Credential-Vorrang

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. Entferne diese bei der Migration von API-Keys.
3	`ANTHROPIC_PROFILE`	Lädt `<config_dir>/configs/<name>.json`. Ein fehlendes benanntes Profil ist ein Fehler, kein Durchfallen.
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 Rückfall 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 workspace_id nur dann, 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 lokalisiert 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 wörtliche Name default

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

Dateilayout

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 eingebacken werden.
`<config_dir>/credentials/<profile>.json`	`version`, das zwischengespeicherte `access_token`, `expires_at` und (für interaktives Login) `refresh_token`.	Geheim. Wird vom SDK mit Modus `0600` geschrieben.

Sowohl die Konfigurationsdatei 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 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

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, 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 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.
`workspace:inference`	Die Inferenz-Endpunkte im Workspace der Regel: Messages (einschließlich Streaming und Token-Zählung), Models und der OpenAI-kompatible Chat-Endpunkt. Verwende dies für Workloads, die nur Claude aufrufen müssen und niemals Files, Skills oder andere Ressourcen verwalten müssen.
`workspace:manage_tunnels`	Die MCP-Tunnels-API: Tunnel erstellen, auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnel archivieren. Das Modalfenster zum Erstellen von Tunneln in der Console sperrt diesen Scope, wenn du eine Regel daraus erstellst.
`org:admin`	Vollzugriff auf die Admin API (Organisationsmitglieder, Einladungen, Workspaces, API-Keys und der Rest). Ein OAuth-`org:admin`-Token kann nur Regeln erstellen oder ändern, die auf `workspace:developer` oder `workspace:inference` beschränkt sind, und kann keinen Issuer aktualisieren, der eine Regel mit einem anderen Scope stützt; siehe die Einschränkungen.

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.

Berechtigungsgrenzen

Der oauth_scope einer Federation-Regel ist eine Obergrenze: Das ausgestellte Token kann sie 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 abzielen muss. Die effektiven Berechtigungen sind die Schnittmenge aus dem Scope der Regel und der Rolle des Service-Accounts.

Regel-`oauth_scope`	Service-Account-`organization_role`	Effektive Berechtigungen
`workspace:developer`	`admin`	Claude-API-Zugriff nur im Workspace der Regel. Der Scope begrenzt das Token unterhalb der Rolle.
`org:admin`	`admin`	Voller Admin-API-Zugriff (Organisationsmitglieder, Einladungen, Workspaces, API-Keys und der Rest), abzüglich der Ausnahmen für OAuth-Aufrufer; siehe Einschränkungen.

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.

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

Feld	Einschränkung
Issuer-, Regel- und Service-Account-`name`	Muss `^[a-z0-9-]+$` entsprechen, Länge 1 bis 255 Zeichen.
`workspace_id`	Beim Erstellen erforderlich, es sei denn, `applies_to_all_workspaces` ist true. 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 Workspace sein.
`applies_to_all_workspaces`	Boolean. Setze `true`, um die Regel in jedem Workspace der Organisation zu aktivieren, anstatt einen zu benennen; entweder dies oder `workspace_id` ist beim Erstellen erforderlich.
`token_lifetime_seconds`	Ganzzahl 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 Aktualisierung.

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.

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

URL-Einschränkungen gelten nur für URLs, die Anthropic anwählt. 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 kann.

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 Schlüssel 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).
Zeitabweichung	Eine Toleranz von 30 Sekunden wird auf `exp`, `nbf` und `iat` angewendet.

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.

Matcher	Typ	Semantik
`subject_prefix`	string	Exakte Übereinstimmung mit dem JWT-`sub`-Claim. Ein abschließendes `` macht daraus einen Präfix-Abgleich (der `sub`-Wert muss mit den Zeichen vor dem `` beginnen). Groß-/Kleinschreibung wird beachtet.
`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 Schlüssel 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` ausgewertet werden 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 ausgewertet wird, gewährt umfassenderen Zugriff als beabsichtigt. Bevorzuge die statischen Matcher, wenn sie deine Einschränkung ausdrücken.

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 sprachliche Äquivalent), der den HTTP-Status, den Antwort-Body und die request_id offenlegt.

Status	Fehler	Ursache	Lösung
400	`invalid_request`	`federation_rule_id` ist fehlerhaft formatiert oder ein erforderliches Anfragefeld fehlt.	Überprüfe die `fdrl_`-ID und dass der Anfrage-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 Schlüssel signiert, der nicht im JWKS enthalten ist.	Aktualisiere im `inline`-Modus den Issuer mit den rotierten Schlüsseln. Bestätige für `discovery` und `explicit_url`, dass der JWKS-Endpunkt auf Port 443 erreichbar ist; wenn der Issuer kürzlich seinen Signaturschlüssel rotiert hat, siehe Schlüsselrotation und Caching.
400	`invalid_grant`	Der JWT-`exp`-Claim liegt in der Vergangenheit (jenseits des 30-Sekunden-Toleranzfensters).	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. Bei `subject_prefix` wird Groß-/Kleinschreibung beachtet. `audience` erfordert eine exakte Element-Übereinstimmung.
400	`invalid_grant`	Die `federation_rule_id` existiert nicht, ist archiviert oder das JWT ist dafür nicht autorisiert (zusammengefasst, 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	Eines 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 sich mit einem API-Key statt zu föderieren	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` ist gesetzt und hat Vorrang.	Entferne die Key- oder Token-Variable.
`FileNotFoundError` bei der ersten Anfrage	Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei verzögert zum Zeitpunkt des Exchange.	Bestätige, dass das Volume mit dem projizierten Token gemountet ist und der Pfad übereinstimmt.
Token-Exchange gelingt, aber eine Claude-API-Anfrage gibt 403 zurück	Der Scope des ausgestellten Tokens gewährt keinen Zugriff auf diesen Endpunkt.	Prüfe den `oauth_scope` der Regel gegen OAuth-Scopes.
Authentifizierung schlägt mit leerem Credential fehl	Eine Credential-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte gewinnen weiterhin ihren Vorrangplatz.	Entferne 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 Seite zum Authentifizierungsverlauf 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, was die folgenden Prüfungen in der Regel überflüssig macht.

Wenn du dennoch vom JWT selbst aus 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 der registrierten issuer_url entsprechen, 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 (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.
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-Toleranzfensters. Wenn die Uhr des Workload-Hosts abgedriftet ist, wird ein ansonsten gültiges Token abgelehnt.
Prüfe die JWKS-Erreichbarkeit
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 auflöst. Rufe für explicit_url die JWKS-URL direkt ab. Bestätige für 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 Exchanges 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 jwks-Feld, wie Anthropic die öffentlichen Schlüssel erhält, die zur Verifizierung von JWT-Signaturen dieses Issuers verwendet werden. Es ist eine diskriminierte Union mit dem Schlüssel type:

`jwks.type`	`jwks`-Form	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 or 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 angewählt.	Dein IdP stellt kein Discovery-Dokument bereit, oder Discovery ist nur intern, aber das JWKS ist öffentlich erreichbar.
`inline`	`{ "type": "inline", "keys": [...] }`	Du lieferst das Array der JWK-Objekte 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 clusterinternen Issuer-URLs oder wenn du explizite Kontrolle über die Schlüsselrotation haben möchtest.

Die diskriminierte Union macht die Begleitfelder konstruktionsbedingt 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.

Schlüsselrotation und Caching

In den Modi discovery und explicit_url cached Anthropic das abgerufene JWKS. Wenn dein Identity Provider einen neuen Signaturschlüssel veröffentlicht und sofort beginnt, Tokens damit zu signieren, können Exchanges, die diese Tokens 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 Identity Provider beginnt, Tokens damit zu signieren, und behalte den abgelösten Schlüssel im JWKS, bis die von ihm signierten Tokens abgelaufen sind. Verwaltete Identity Provider 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.

Im inline-Modus gibt es keine automatische Schlüsselaktualisierung. Wenn dein Identity Provider seine Signaturschlüssel 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.

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

Token-Exchange-Anfrage

Feld	Erforderlich	Beschreibung
`grant_type`	Ja	Immer `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Ja	Das von deinem Identity Provider ausgestellte OIDC-JWT.
`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 Workspace, 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 von der übereinstimmenden Regel gewährte OAuth-Scope.

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`	Eines 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`	Eines von `_TOKEN_FILE` oder `_TOKEN`	Das wörtliche JWT als String. Verwende dies, wenn deine Plattform das Token als Umgebungsvariable statt als Datei injiziert.	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	Ja	Getaggte ID des Ziel-Anthropic-Service-Accounts, als der das ausgestellte Access-Token agiert.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Bedingt	Getaggte ID des Workspace, 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 Workspace-Wechsel einen neuen Exchange erfordert.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Nein	Name eines zu ladenden Konfigurationsprofils. Hat Vorrang vor den Federation-Umgebungsvariablen in dieser Tabelle.	`staging-profile`

Credential-Vorrang

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. Entferne diese bei der Migration von API-Keys.
3	`ANTHROPIC_PROFILE`	Lädt `<config_dir>/configs/<name>.json`. Ein fehlendes benanntes Profil ist ein Fehler, kein Durchfallen.
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 Rückfall auf ein Profil namens `default`.

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Das SDK lokalisiert 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 wörtliche Name default

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

Dateilayout

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 eingebacken werden.
`<config_dir>/credentials/<profile>.json`	`version`, das zwischengespeicherte `access_token`, `expires_at` und (für interaktives Login) `refresh_token`.	Geheim. Wird 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, 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 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.
`workspace:inference`	Die Inferenz-Endpunkte im Workspace der Regel: Messages (einschließlich Streaming und Token-Zählung), Models und der OpenAI-kompatible Chat-Endpunkt. Verwende dies für Workloads, die nur Claude aufrufen müssen und niemals Files, Skills oder andere Ressourcen verwalten müssen.
`workspace:manage_tunnels`	Die MCP-Tunnels-API: Tunnel erstellen, auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnel archivieren. Das Modalfenster zum Erstellen von Tunneln in der Console sperrt diesen Scope, wenn du eine Regel daraus erstellst.
`org:admin`	Vollzugriff auf die Admin API (Organisationsmitglieder, Einladungen, Workspaces, API-Keys und der Rest). Ein OAuth-`org:admin`-Token kann nur Regeln erstellen oder ändern, die auf `workspace:developer` oder `workspace:inference` beschränkt sind, und kann keinen Issuer aktualisieren, der eine Regel mit einem anderen Scope stützt; siehe die Einschränkungen.

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.

Berechtigungsgrenzen

Regel-`oauth_scope`	Service-Account-`organization_role`	Effektive Berechtigungen
`workspace:developer`	`admin`	Claude-API-Zugriff nur im Workspace der Regel. Der Scope begrenzt das Token unterhalb der Rolle.
`org:admin`	`admin`	Voller Admin-API-Zugriff (Organisationsmitglieder, Einladungen, Workspaces, API-Keys und der Rest), abzüglich der Ausnahmen für OAuth-Aufrufer; siehe Einschränkungen.

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.

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

Feld	Einschränkung
Issuer-, Regel- und Service-Account-`name`	Muss `^[a-z0-9-]+$` entsprechen, Länge 1 bis 255 Zeichen.
`workspace_id`	Beim Erstellen erforderlich, es sei denn, `applies_to_all_workspaces` ist true. 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 Workspace sein.
`applies_to_all_workspaces`	Boolean. Setze `true`, um die Regel in jedem Workspace der Organisation zu aktivieren, anstatt einen zu benennen; entweder dies oder `workspace_id` ist beim Erstellen erforderlich.
`token_lifetime_seconds`	Ganzzahl 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 Aktualisierung.

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.

URL-Validierungsfehler geben 400 invalid_request_error zurück, wobei der Feldname als Präfix der Fehlermeldung vorangestellt ist (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 Schlüssel 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).
Zeitabweichung	Eine Toleranz von 30 Sekunden wird auf `exp`, `nbf` und `iat` angewendet.

Semantik des Regelabgleichs

Matcher	Typ	Semantik
`subject_prefix`	string	Exakte Übereinstimmung mit dem JWT-`sub`-Claim. Ein abschließendes `` macht daraus einen Präfix-Abgleich (der `sub`-Wert muss mit den Zeichen vor dem `` beginnen). Groß-/Kleinschreibung wird beachtet.
`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 Schlüssel 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` ausgewertet werden 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 formatiert oder ein erforderliches Anfragefeld fehlt.	Überprüfe die `fdrl_`-ID und dass der Anfrage-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 Schlüssel signiert, der nicht im JWKS enthalten ist.	Aktualisiere im `inline`-Modus den Issuer mit den rotierten Schlüsseln. Bestätige für `discovery` und `explicit_url`, dass der JWKS-Endpunkt auf Port 443 erreichbar ist; wenn der Issuer kürzlich seinen Signaturschlüssel rotiert hat, siehe Schlüsselrotation und Caching.
400	`invalid_grant`	Der JWT-`exp`-Claim liegt in der Vergangenheit (jenseits des 30-Sekunden-Toleranzfensters).	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. Bei `subject_prefix` wird Groß-/Kleinschreibung beachtet. `audience` erfordert eine exakte Element-Übereinstimmung.
400	`invalid_grant`	Die `federation_rule_id` existiert nicht, ist archiviert oder das JWT ist dafür nicht autorisiert (zusammengefasst, 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	Eines 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 sich mit einem API-Key statt zu föderieren	`ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` ist gesetzt und hat Vorrang.	Entferne die Key- oder Token-Variable.
`FileNotFoundError` bei der ersten Anfrage	Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei verzögert zum Zeitpunkt des Exchange.	Bestätige, dass das Volume mit dem projizierten Token gemountet ist und der Pfad übereinstimmt.
Token-Exchange gelingt, aber eine Claude-API-Anfrage gibt 403 zurück	Der Scope des ausgestellten Tokens gewährt keinen Zugriff auf diesen Endpunkt.	Prüfe den `oauth_scope` der Regel gegen OAuth-Scopes.
Authentifizierung schlägt mit leerem Credential fehl	Eine Credential-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte gewinnen weiterhin ihren Vorrangplatz.	Entferne 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 vom JWT selbst aus 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 der registrierten issuer_url entsprechen, 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 (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.
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-Toleranzfensters. Wenn die Uhr des Workload-Hosts abgedriftet ist, wird ein ansonsten gültiges Token abgelehnt.
Prüfe die JWKS-Erreichbarkeit
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 auflöst. Rufe für explicit_url die JWKS-URL direkt ab. Bestätige für 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 Exchanges bis zu einer Minute lang fehlschlagen, während der JWKS-Cache von Anthropic aktualisiert wird. Siehe Schlüsselrotation und Caching.

JWKS-Quellmodi

`jwks.type`	`jwks`-Form	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 or 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 angewählt.	Dein IdP stellt kein Discovery-Dokument bereit, oder Discovery ist nur intern, aber das JWKS ist öffentlich erreichbar.
`inline`	`{ "type": "inline", "keys": [...] }`	Du lieferst das Array der JWK-Objekte 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 clusterinternen Issuer-URLs oder wenn du explizite Kontrolle über die Schlüsselrotation haben möchtest.

Schlüsselrotation und Caching

Was this page helpful?

Token-Exchange-Anfrage

Token-Exchange-Antwort

Umgebungsvariablen

Credential-Vorrang

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Aktives Profil

Dateilayout

Beispiel für ein Federation-Profil

OAuth-Scopes

Berechtigungsgrenzen

Validierungsregeln

Ressourcenfelder

URL-Felder

JWT-Verifizierung

Semantik des Regelabgleichs

CEL-Auswertungsumgebung

Fehler

Token-Exchange-Fehler

Häufige SDK-seitige Fehler

Fehlerbehebung bei einem fehlgeschlagenen Exchange

JWKS-Quellmodi

Schlüsselrotation und Caching

Token-Exchange-Anfrage

Token-Exchange-Antwort

Umgebungsvariablen

Credential-Vorrang

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Aktives Profil

Dateilayout

Beispiel für ein Federation-Profil

OAuth-Scopes

Berechtigungsgrenzen

Validierungsregeln

Ressourcenfelder

URL-Felder

JWT-Verifizierung

Semantik des Regelabgleichs

CEL-Auswertungsumgebung

Fehler

Token-Exchange-Fehler

Häufige SDK-seitige Fehler

Fehlerbehebung bei einem fehlgeschlagenen Exchange

JWKS-Quellmodi

Schlüsselrotation und Caching

Token-Exchange-Anfrage

Token-Exchange-Antwort

Umgebungsvariablen

Credential-Vorrang

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Aktives Profil

Dateilayout

Beispiel für ein Federation-Profil

OAuth-Scopes

Berechtigungsgrenzen

Validierungsregeln

Ressourcenfelder

URL-Felder

JWT-Verifizierung

Semantik des Regelabgleichs

CEL-Auswertungsumgebung

Fehler

Token-Exchange-Fehler

Häufige SDK-seitige Fehler

Fehlerbehebung bei einem fehlgeschlagenen Exchange

JWKS-Quellmodi

Schlüsselrotation und Caching

Token-Exchange-Anfrage

Token-Exchange-Antwort

Umgebungsvariablen

Credential-Vorrang

Profil-Konfigurationsdatei

Konfigurationsverzeichnis

Aktives Profil

Dateilayout

Beispiel für ein Federation-Profil

OAuth-Scopes

Berechtigungsgrenzen

Validierungsregeln

Ressourcenfelder

URL-Felder

JWT-Verifizierung

Semantik des Regelabgleichs

CEL-Auswertungsumgebung

Fehler

Token-Exchange-Fehler

Häufige SDK-seitige Fehler

Fehlerbehebung bei einem fehlgeschlagenen Exchange

JWKS-Quellmodi

Schlüsselrotation und Caching