--- title: WIF-Referenz url: https://platform.claude.com/docs/de/manage-claude/wif-reference description: Umgebungsvariablen, Validierungsregeln, Profilkonfiguration und Fehlerreferenz für Workload Identity Federation. --- Diese Seite fasst die Konfigurationsflächen, Validierungseinschränkungen und Fehlerzuordnungen für [Workload Identity Federation](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation) zusammen. Für Einrichtungsanleitungen siehe die [Provider-Leitfäden](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation#identity-providers). ## Token-Austauschanfrage `POST /v1/oauth/token` akzeptiert einen JSON-Body mit dem `jwt-bearer`-Grant gemäß [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). Das SDK erstellt diese Anfrage für dich aus den [Umgebungsvariablen](https://platform.claude.com/docs/de/manage-claude/wif-reference#environment-variables); 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 geprägte Token beschränkt werden soll. Erforderlich, wenn die Regel für mehr als einen Workspace aktiviert ist. Wenn sie weggelassen wird, wählt der Server den einzigen aktivierten Workspace der Regel. Das Literal `default` funktioniert ebenfalls für den Default Workspace der Organisation, ist aber abgekündigt; verwende die `wrkspc_...`-ID dieses Workspace. | ## Token-Austauschantwort `POST /v1/oauth/token` gibt eine standardmäßige OAuth-2.0-Token-Antwort zurück ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-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_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-Austausch 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 auf der Seite [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) in der Claude Console. | `00000000-0000-0000-0000-000000000000` | | `ANTHROPIC_IDENTITY_TOKEN_FILE` | Eine von `_TOKEN_FILE` oder `_TOKEN` | Dateisystempfad zum JWT, das von deinem „identity provider" (Identitätsanbieter), oder IdP, ausgestellt wurde. Das SDK liest diese Datei bei jedem Austausch neu ein, sodass projizierte Tokens, die auf der Festplatte rotiert werden, 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 Workspace, auf den das geprägte Token beschränkt werden soll. Erforderlich, wenn die Federation-Regel für mehr als einen Workspace aktiviert ist; optional, wenn die Regel an einen einzelnen Workspace gebunden ist. Das geprägte Token wird zum Zeitpunkt des Austauschs auf diesen Workspace beschränkt, daher erfordert ein Wechsel des Workspace einen neuen Austausch. Das Literal `default` funktioniert ebenfalls für den Default Workspace, ist aber abgekündigt; verwende dessen `wrkspc_...`-ID. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | Nein | Name eines zu ladenden [Konfigurationsprofils](https://platform.claude.com/docs/de/manage-claude/wif-reference#profile-configuration-file). Hat Vorrang vor den Federation-Umgebungsvariablen in dieser Tabelle. | `staging-profile` | Der direkte Umgebungsvariablen-Federation-Pfad 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 zusätzlich gelesen, steuert aber nicht die Aktivierung. Eine Variable, die auf einen leeren String gesetzt ist, belegt dennoch ihren Platz in der Kette der Anmeldedaten-Priorität. Wenn `ANTHROPIC_API_KEY=""` exportiert wird, wählt das SDK den API-Key-Pfad mit einem leeren Key, anstatt zur Federation durchzufallen. Hebe ungenutzte Anmeldedaten-Variablen auf, anstatt sie zu leeren. ### Anmeldedaten-Priorität Das SDK löst Anmeldedaten in dieser Reihenfolge auf. Die erste Quelle, die ein Anmeldedatum 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 die Federation vollständig. Hebe diese auf, wenn du von API-Keys migrierst. | | 3 | `ANTHROPIC_PROFILE` | Lädt `/configs/.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 `/active_config`, mit Rückfall auf ein Profil namens `default`. | Wenn ein Profil geladen wird, füllen Umgebungsvariablen alle Felder, 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. ## Profilkonfigurationsdatei 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: 1. `$ANTHROPIC_CONFIG_DIR` 2. `~/.config/anthropic` unter Linux und macOS 3. `%APPDATA%\Anthropic` unter Windows ### Aktives Profil Der aktive Profilname wird in dieser Reihenfolge aufgelöst: 1. `$ANTHROPIC_PROFILE` 2. Der Inhalt von `/active_config` (eine einzeilige Datei, die von `ant profile activate ` geschrieben wird) 3. Der literale Name `default` Claude Code und das Claude Agent SDK berücksichtigen dieselbe Auflösungsreihenfolge, sodass ein hier konfiguriertes Federation-Profil diese Tools auch ohne zusätzliche Einrichtung authentifiziert. ### Dateilayout | Pfad | Inhalt | Sensibilität | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `/configs/.json` | `version`, der `authentication`-Block, `organization_id`, `workspace_id` und `base_url`. | Nicht geheim. Sicher zum Committen oder Einbacken in ein Image. | | `/credentials/.json` | `version`, das zwischengespeicherte `access_token`, `expires_at` und (für interaktives Login) `refresh_token`. | Geheim. Vom SDK mit Modus `0600` geschrieben. | 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 ```json 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 geprägte Access-Token aufrufen kann. | Scope | Gewährt Zugriff auf | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Alle nicht-administrativen Claude-API-Endpunkte im Workspace der Regel: [Messages](https://platform.claude.com/docs/de/api/messages) (einschließlich Streaming und Token-Zählung), [Models](https://platform.claude.com/docs/de/api/models/list), [Managed Agents](https://platform.claude.com/docs/de/managed-agents/overview) und ihre Sessions, [Files](https://platform.claude.com/docs/de/build-with-claude/files) und [Skills](https://platform.claude.com/docs/de/build-with-claude/skills-guide). Dies entspricht dem Zugriff, den ein Workspace-API-Key im selben Workspace hat. | | `workspace:inference` | Die Inferenz-Endpunkte im Workspace der Regel: [Messages](https://platform.claude.com/docs/de/api/messages) (einschließlich Streaming und Token-Zählung), [Models](https://platform.claude.com/docs/de/api/models/list) und der [OpenAI-kompatible Chat-Endpunkt](https://platform.claude.com/docs/de/cli-sdks-libraries/libraries/openai-sdk). 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](https://platform.claude.com/docs/de/agents-and-tools/mcp-tunnels/reference#tunnels-api): Tunnel erstellen, auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnel archivieren. Das Create-Tunnel-Modalfenster der Console sperrt diesen Scope, wenn du eine Regel daraus erstellst. | | `org:admin` | Vollzugriff auf die [Admin-API](https://platform.claude.com/docs/de/manage-claude/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](https://platform.claude.com/docs/de/manage-claude/wif-admin-api#permissions-and-constraints). | Eine Anfrage an einen Endpunkt außerhalb des Scopes des Tokens gibt HTTP 403 zurück. Feinkörnigere Scopes (pro Ressource oder Lesen versus Schreiben) sind derzeit nicht verfügbar. ### Berechtigungsgrenzen Der `oauth_scope` einer Federation-Regel ist eine Obergrenze: Das geprägte Token kann sie niemals überschreiten. Die `organization_role` (`developer` oder `admin`) des Ziel-Service-Accounts bestimmt, welche Scopes gewährbar sind, 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` | Vollständiger Admin-API-Zugriff (Organisationsmitglieder, Einladungen, Workspaces, API-Keys und der Rest), abzüglich der OAuth-Aufrufer-Ausnahmen; siehe [Einschränkungen](https://platform.claude.com/docs/de/manage-claude/wif-admin-api#permissions-and-constraints). | ## Validierungsregeln Anthropic erzwingt diese Einschränkungen, wenn du Issuer und Regeln erstellst oder aktualisierst und wenn ein eingehendes JWT zum Austauschzeitpunkt verifiziert wird. Vollständige Parameterdetails und Antwortschemata findest du in der [API-Referenz für Service-Accounts](https://platform.claude.com/docs/de/api/organization/service_accounts), der [API-Referenz für Federation-Issuer](https://platform.claude.com/docs/de/api/organization/federation/issuers) und der [API-Referenz für Federation-Regeln](https://platform.claude.com/docs/de/api/organization/federation/rules). ### 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 unter dieser Regel geprägte Tokens gelten. 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` | Integer zwischen `60` und `86400` (1 Minute bis 24 Stunden). Standard `3600`. Werte außerhalb dieses Bereichs werden zur Anfragezeit abgelehnt. Siehe [Token-Lebensdauer und Aktualisierung](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation#token-lifetime-and-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. | URL-Validierungsfehler 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 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 einem Schlüssel im JWKS des Issuers entspricht. 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. | | Einmalige Verwendung | Eine Assertion mit einem `jti`-Claim kann pro Issuer nur einmal ausgetauscht werden: Ein wiederholter Austausch mit derselben `jti` wird als Replay abgelehnt. Das Feld `check_jti` des Issuers (standardmäßig aktiviert) steuert diese Prüfung; Assertions ohne `jti`-Claim unterliegen ihr nicht. Siehe die [API-Referenz für Federation-Issuer](https://platform.claude.com/docs/de/api/organization/federation/issuers). | | 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). | | Uhrenabweichung | Auf `exp`, `nbf` und `iat` wird eine Toleranz von 30 Sekunden angewendet. | ## Regelabgleich-Semantik 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 von einem Issuer akzeptieren würden. | Matcher | Typ | Semantik | | ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | Exakter Abgleich gegen den JWT-`sub`-Claim. Ein abschließendes `*` macht es zu einem Präfix-Abgleich (der `sub`-Wert muss mit den Zeichen vor dem `*` beginnen). Groß-/Kleinschreibung wird beachtet. | | `audience` | string | Der JWT-`aud`-Claim muss diesen exakten String enthalten. Wenn `aud` ein Array ist, erfüllt jedes exakt übereinstimmende Element die Prüfung. | | `claims` | map\ | 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](https://cel.dev/)-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: ```text wrap 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 breiteren Zugriff als beabsichtigt. Bevorzuge die statischen Matcher, wenn sie deine Einschränkung ausdrücken. ## Fehler ### Token-Austauschfehler `POST /v1/oauth/token` gibt Fehler im standardmäßigen [API-Fehlerformat](https://platform.claude.com/docs/de/api/errors) zurück. Das SDK meldet einen Austauschfehler als `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), der den HTTP-Status und die Fehlerdetails aus dem Antwort-Body liefert. Die Request-ID befindet sich in Python, TypeScript und Ruby am Fehlerobjekt und in Java in den Antwort-Headern der Exception. In Go ist sie nur in der Fehlermeldung enthalten, da sich der Typ des Fehlers in einem internen Paket befindet; die Fehler in C# und PHP enthalten sie nicht. | Status | Fehler | Ursache | Lösung | | ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | `federation_rule_id` ist fehlerhaft oder ein erforderliches Anfragefeld fehlt. | Überprüfe die `fdrl_`-ID und dass der Anfrage-Body alle erforderlichen Felder enthält. | | 400 | `invalid_request_error` | `workspace_id` ist vorhanden, aber keine wohlgeformte `wrkspc_...`-ID oder das Literal `default`. | Korrigiere den `workspace_id`-Wert; die Antwortmeldung nennt das erwartete Format. | | 401 | `authentication_error` | 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"`. | | 401 | `authentication_error` | JWKS-Abruf fehlgeschlagen, JWKS ist veraltet oder das JWT wurde mit einem Key signiert, der nicht im JWKS 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 Signaturschlüssel rotiert hat, siehe [Schlüsselrotation und Caching](https://platform.claude.com/docs/de/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | Der JWT-`exp`-Claim liegt in der Vergangenheit (jenseits des 30-Sekunden-Abweichungsfensters). | Bestätige, dass dein Identity-Provider ein frisches Token projiziert und das SDK die Token-Datei erneut liest. | | 401 | `authentication_error` | 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` beachtet Groß-/Kleinschreibung. `audience` erfordert einen exakten Element-Abgleich. | | 401 | `authentication_error` | Die `federation_rule_id` existiert nicht, ist archiviert oder das JWT ist dafür nicht autorisiert (konsolidiert, um Enumeration zu verhindern). | Bestätige die Regel-ID in der Claude Console und dass die Regel nicht archiviert wurde. | | 401 | `authentication_error` | Die Federation-Regel ist für mehr als einen Workspace aktiviert und die Anfrage lässt `workspace_id` weg. Der Authentifizierungsverlaufseintrag zeigt den Grund `workspace_id_required`. | 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-Austauschanfrage](https://platform.claude.com/docs/de/manage-claude/wif-reference#token-exchange-request). | 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](https://platform.claude.com/settings/workload-identity-federation?tab=history) in der Claude Console 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 oben genannte `400 invalid_request_error`-Familie), 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 | Symptom | Ursache | Lösung | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | SDK meldet „no credentials" statt auszutauschen | 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 gewinnt die Priorität. | Hebe die Key- oder Token-Variable auf. | | `FileNotFoundError` bei der ersten Anfrage | Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei verzögert zum Austauschzeitpunkt. | Bestätige, dass das Volume mit dem projizierten Token gemountet ist und der Pfad übereinstimmt. | | Token-Austausch gelingt, aber eine Claude-API-Anfrage gibt 403 zurück | Der Scope des geprägten Tokens gewährt keinen Zugriff auf diesen Endpunkt. | Überprüfe den `oauth_scope` der Regel gegen [OAuth-Scopes](https://platform.claude.com/docs/de/manage-claude/wif-reference#oauth-scopes). | | Authentifizierung schlägt mit leerem Anmeldedatum fehl | Eine Anmeldedaten-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte gewinnen dennoch ihren Prioritätsplatz. | Hebe die Variable mit `unset VAR` auf, anstatt `VAR=""`. | ## Einen fehlgeschlagenen Austausch beheben Eine `401` `authentication_error`-Antwort ist absichtlich undurchsichtig und ihre Meldung ist immer `Authentication failed`; der Ablehnungsgrund wird im Authentifizierungsverlauf aufgezeichnet, nicht in der Antwort. Beginne mit der [Authentifizierungsverlaufsseite](https://platform.claude.com/settings/workload-identity-federation?tab=history) in der Claude Console. Jüngste Austauschversuche zeigen den ausgewerteten Issuer und die Regel, die inspizierten JWT-Claims und welcher Validierungsschritt fehlgeschlagen ist, was normalerweise die folgenden Prüfungen abkürzt. Ein häufiger undurchsichtiger Fehler ist eine wiederholte Assertion: Eine Assertion, die einen `jti`-Claim trägt, kann [nur einmal ausgetauscht](https://platform.claude.com/docs/de/manage-claude/wif-reference#jwt-verification) werden, sodass ein Workload, der dasselbe JWT erneut sendet (eine Retry-Schleife oder eine Aktualisierung, die ein nicht rotiertes Token erneut liest), beim zweiten Austausch abgelehnt wird. Die Authentifizierungsverlaufsseite zeigt diese Versuche mit dem Grund `jti_reused`; die Lösung besteht darin, für jeden Austausch eine frische Assertion zu prägen. Wenn du immer noch vom JWT selbst aus debuggen musst, arbeite diese Prüfungen der Reihe nach durch: Dekodiere die gesendete Assertion, damit du jeden Claim mit deiner Issuer- und Regelkonfiguration vergleichen kannst: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` Der dekodierte `iss`-Claim muss Byte für Byte der registrierten `issuer_url` entsprechen, einschließlich Schema, Port und jedem abschließenden Schrägstrich. Eine Abweichung bei einem einzigen Zeichen lässt die Verifizierung fehlschlagen. Der dekodierte `aud`-Claim muss den `audience`-Wert der Regel als exakten Abgleich enthalten. Wenn `aud` ein Array ist, muss ein Element exakt übereinstimmen. 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. `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 abgedriftet ist, wird ein ansonsten gültiges Token abgelehnt. Für den `discovery`-Modus rufe `/.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 Signaturschlüssel des Issuers seit der Registrierung der Keys 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](https://platform.claude.com/docs/de/manage-claude/wif-reference#key-rotation-and-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 von diesem Issuer verwendet werden. Es ist eine diskriminierte Union, die auf `type` basiert: | `jwks.type` | `jwks`-Form | Verhalten | Verwenden, wenn | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `discovery` (Standard) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` ist optional; setze es, wenn die Discovery-URL von `issuer_url` abweicht) | Anthropic ruft `/.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 gegen den 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 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 Schlüsselrotation möchtest. | Die diskriminierte Union macht die Begleitfelder durch Konstruktion gegenseitig ausschließend. Sowohl `discovery` als auch `explicit_url` akzeptieren außerdem 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` speichert Anthropic das abgerufene JWKS zwischen. Wenn dein Identity-Provider einen neuen Signaturschlüssel veröffentlicht und sofort damit beginnt, Tokens damit zu signieren, können Austausche, die diese Tokens präsentieren, bis zu 1 Minute lang mit einem Signaturfehler fehlschlagen, während der Cache aktualisiert wird. Um dieses Fenster 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 Key im JWKS, bis die damit signierten Tokens abgelaufen sind. Verwaltete Identity-Provider folgen dieser Disziplin typischerweise von selbst. Wenn du deinen eigenen Issuer betreibst (einen selbstverwalteten Kubernetes-Cluster, einen SPIRE-OIDC-Discovery-Provider oder einen Okta-Custom-Authorization-Server mit einer konfigurierten Rotationskadenz), bestätige, dass deine Rotationsrichtlinie neue Keys 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-Austausche bei der Signaturverifizierung fehl.