--- 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 Konfigurationsoptionen, Validierungseinschränkungen und Fehlerzuordnungen für [Workload Identity Federation](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation) zusammen. Schritt-für-Schritt-Anleitungen zur Einrichtung findest du in den [Anbieter-Leitfäden](https://platform.claude.com/docs/de/manage-claude/workload-identity-federation#identity-providers). ## Token-Exchange-Anfrage `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 den einzelnen Anbieter-Leitfäden zeigen den rohen Body. | Feld | Erforderlich | Beschreibung | | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | Ja | Immer `urn:ietf:params:oauth:grant-type:jwt-bearer`. | | `assertion` | Ja | Das von deinem Identitätsanbieter 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-Servicekontos. | | `workspace_id` | Bedingt | Getaggte ID (`wrkspc_...`) des Workspace, auf den das ausgestellte 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. Der Literalwert `default` funktioniert ebenfalls für den Default Workspace der Organisation, ist aber abgekündigt; verwende stattdessen die `wrkspc_...`-ID dieses Workspace. | ## Token-Exchange-Antwort `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 passenden 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 Literal-String. Verwende dies, wenn deine Plattform das Token als Umgebungsvariable statt als Datei bereitstellt. | `eyJhbGciOiJSUzI1NiIs...` | | `ANTHROPIC_SERVICE_ACCOUNT_ID` | Ja | Getaggte ID des Anthropic-Ziel-Servicekontos, als das das ausgestellte Access-Token agiert. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Bedingt | Getaggte ID des Workspace, auf den das ausgestellte 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 ausgestellte Token wird zum Zeitpunkt des Austauschs auf diesen Workspace beschränkt, daher erfordert ein Wechsel des Workspace einen neuen Austausch. Der Literalwert `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 Federation-Pfad über Umgebungsvariablen wird nur aktiviert, wenn `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` und eine von `ANTHROPIC_IDENTITY_TOKEN_FILE` oder `ANTHROPIC_IDENTITY_TOKEN` alle gesetzt sind. `ANTHROPIC_WORKSPACE_ID` wird zusätzlich gelesen, steuert die Aktivierung aber nicht. Eine Variable, die auf einen leeren String gesetzt ist, kann trotzdem ihren Platz in der Rangfolge der Anmeldedaten belegen. Entferne nicht verwendete Anmeldedaten-Variablen mit unset, anstatt sie zu leeren. ### Rangfolge der Anmeldedaten Das SDK löst Anmeldedaten in dieser Reihenfolge auf. Die erste Quelle, die Anmeldedaten liefert, gewinnt. | Reihenfolge | Quelle | Hinweise | | ----------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | Konstruktorargument (`api_key=`, `auth_token=`, `credentials=`) | Überschreibt immer alles andere. | | 2 | `ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` | Überdeckt Federation vollständig. Entferne diese bei der Migration von API-Keys. | | 3 | `ANTHROPIC_PROFILE` | Lädt `/configs/.json`. Ein fehlendes benanntes Profil ist ein Fehler, kein Durchfallen zur nächsten Quelle. | | 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`. | In der `ant` CLI rangieren die Einstellungen für [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/de/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) nach den Umgebungsvariablen für die Föderation und vor dem aktiven Profil. Die Einstellungen sind das Projekt, die Workspace-ID und der Standort. Du legst sie mit den `--google-cloud-*`-Flags oder den `ANTHROPIC_GOOGLE_CLOUD_*`-Variablen fest. Die CLI verwendet diese Einstellungen, sobald eine davon gesetzt ist. Mit diesen Einstellungen bezieht die CLI ihre Anmeldedaten aus den Google Application Default Credentials. Wenn ein Profil geladen wird, füllen Umgebungsvariablen alle Felder, die das Profil auslässt, überschreiben aber niemals Felder, die das Profil explizit setzt. Beispielsweise füllt `ANTHROPIC_WORKSPACE_ID` das Feld `workspace_id` nur, wenn das aktive Profil es nicht setzt. ## Profil-Konfigurationsdatei Ein Profil ist eine benannte Konfigurationsdatei, die sowohl das SDK als auch die `ant`-CLI lesen. Mit Profilen kannst du Federation-Parameter mit deinem Container-Image ausliefern oder zwischen Umgebungen wechseln, ohne Code zu ändern. ### Konfigurationsverzeichnis Das SDK ermittelt das Konfigurationsverzeichnis in dieser Reihenfolge: 1. `$ANTHROPIC_CONFIG_DIR` 2. `~/.config/anthropic` unter Linux und macOS 3. `%APPDATA%\Anthropic` unter Windows ### Aktives Profil Der Name des aktiven Profils wird in dieser Reihenfolge aufgelöst: 1. `$ANTHROPIC_PROFILE` 2. Der Inhalt von `/active_config` (eine einzeilige Datei, die von `ant profile activate ` geschrieben wird) 3. Der Literalname `default` Claude Code und das Claude Agent SDK berücksichtigen dieselbe Auflösungsreihenfolge, sodass ein hier konfiguriertes Federation-Profil auch diese Tools ohne zusätzliche Einrichtung authentifiziert. ### Dateistruktur | Pfad | Inhalt | Sensibilität | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | `/configs/.json` | `version`, der `authentication`-Block, `organization_id`, `workspace_id` und `base_url`. | Nicht geheim. Kann sicher committet oder in ein Image eingebaut werden. | | `/credentials/.json` | `version`, das zwischengespeicherte `access_token`, `expires_at` und (bei interaktiver Anmeldung) `refresh_token`. | Geheim. Wird vom SDK mit dem Modus `0600` geschrieben. | Sowohl die Konfigurationsdatei als auch die Anmeldedatendatei enthalten ein String-Feld `version` auf oberster Ebene im Format `major.minor` (derzeit `"1.0"`). Das SDK schreibt dieses Feld automatisch, damit zukünftige Versionen ältere Formate erkennen und migrieren können; lass es weg, wenn du eine Konfiguration von Hand erstellst, und das SDK behandelt die Datei als aktuelle Version. ### Beispiel für ein Federation-Profil ```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, 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](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 deren 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): Tunnels erstellen, auflisten und abrufen, CA-Zertifikate registrieren und archivieren, das Tunnel-Token anzeigen und rotieren sowie Tunnels archivieren. Das Modalfenster zum Erstellen von Tunnels in der Console legt diesen Scope fest, wenn du darüber eine Regel erstellst. | | `org:admin` | Vollständiger Zugriff 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 mit dem Scope `workspace:developer` oder `workspace:inference` erstellen oder ändern und kann keinen Issuer aktualisieren, der einer Regel mit einem anderen Scope zugrunde liegt; 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. Feinere Scopes (pro Ressource oder Lesen versus Schreiben) sind derzeit nicht verfügbar. ### Berechtigungsgrenzen Der `oauth_scope` einer Federation-Regel ist eine Obergrenze: Das ausgestellte Token kann sie niemals überschreiten. Die `organization_role` (`developer` oder `admin`) des Ziel-Servicekontos bestimmt, welche Scopes gewährt werden können, daher muss eine Regel, die `org:admin` gewährt, auf ein Servicekonto mit `organization_role=admin` abzielen. Die effektiven Berechtigungen sind die Schnittmenge aus dem Scope der Regel und der Rolle des Servicekontos. | `oauth_scope` der Regel | `organization_role` des Servicekontos | 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 Ausnahmen für OAuth-Aufrufer; siehe [Einschränkungen](https://platform.claude.com/docs/de/manage-claude/wif-admin-api#permissions-and-constraints). | ## Validierungsregeln Anthropic setzt diese Einschränkungen durch, wenn du Issuer und Regeln erstellst oder aktualisierst, sowie bei der Überprüfung eines eingehenden JWT zum Zeitpunkt des Austauschs. Vollständige Parameterdetails und Antwortschemata findest du in der [API-Referenz für Servicekonten](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 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` von Issuer, Regel und Servicekonto | Muss `^[a-z0-9-]+$` entsprechen, Länge 1 bis 255 Zeichen. | | `workspace_id` | Beim Erstellen erforderlich, sofern `applies_to_all_workspaces` nicht true ist. Der Workspace (`wrkspc_...`), dessen Kontingent, Abrechnung und „rate limits" (Ratenlimits) für unter dieser Regel ausgestellte Tokens gelten. Muss ein Workspace in derselben Organisation sein, und das Ziel-Servicekonto 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](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-Anbieter sein. Muss zu öffentlichen IP-Adressen aufgelöst werden; IP-Literale werden nicht akzeptiert. | URL-Validierungsfehler geben `400 invalid_request_error` zurück, wobei der Feldname der Fehlermeldung vorangestellt ist (zum Beispiel `issuer_url: url must use https scheme`). URL-Einschränkungen gelten nur für URLs, die Anthropic aufruft. In den JWKS-Modi `explicit_url` und `inline` sowie im Modus `discovery`, wenn `jwks.discovery_base` gesetzt ist, wird die `issuer_url` als String mit dem JWT-Claim `iss` verglichen und niemals abgerufen, sodass sie auf einen internen Hostnamen oder einen nicht standardmäßigen Port verweisen darf. ### JWT-Überprüfung | 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 | Für `exp`, `nbf` und `iat` wird eine Toleranz von 30 Sekunden 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 | Exakter Abgleich mit dem JWT-Claim `sub`. 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-Claim `aud` muss genau diesen 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 | Die vollständige dekodierte JWT-Claim-Menge. 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 können. ## Fehler ### Fehler beim Token-Austausch `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 fehlgeschlagenen Austausch 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 enthält. Die Request-ID befindet sich in Python, TypeScript und Ruby am Fehler und in Java in den Antwort-Headern der Exception. In Go ist sie nur in der Fehlermeldung enthalten, da sich der Typ des Fehlers in einem internen Paket befindet; die Fehler in C# und PHP enthalten sie nicht. | 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 ob der Anfrage-Body alle erforderlichen Felder enthält. | | 400 | `invalid_request_error` | `workspace_id` ist vorhanden, aber keine wohlgeformte `wrkspc_...`-ID oder der Literalwert `default`. | Korrigiere den `workspace_id`-Wert; die Antwortnachricht nennt das erwartete Format. | | 401 | `authentication_error` | Der JWT-Claim `iss` 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` | Der JWKS-Abruf ist fehlgeschlagen, das 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 bei `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](https://platform.claude.com/docs/de/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | Der JWT-Claim `exp` liegt in der Vergangenheit (jenseits des 30-Sekunden-Toleranzfensters). | Bestätige, dass dein Identitätsanbieter ein frisches Token projiziert und das SDK die Token-Datei neu einliest. | | 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. Bei `subject_prefix` wird Groß-/Kleinschreibung beachtet. `audience` erfordert eine exakte Übereinstimmung eines Elements. | | 401 | `authentication_error` | 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. | | 401 | `authentication_error` | Die Federation-Regel ist für mehr als einen Workspace aktiviert und die Anfrage lässt `workspace_id` weg. Der Eintrag im Authentifizierungsverlauf zeigt den Grund `workspace_id_required`. | Setze `ANTHROPIC_WORKSPACE_ID` (oder das Body-Feld `workspace_id` bei einer rohen Anfrage) auf die `wrkspc_...`-ID, auf die das Token beschränkt werden soll. Siehe [Token-Exchange-Anfrage](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 festgehalten, zum Beispiel `match_subject_prefix`, wenn der `sub`-Claim das `subject_prefix` der Regel nicht erfüllt, oder `workspace_id_required`, wenn die Regel mehrere Workspaces umfasst und die Anfrage keinen benennt. Anfragen, die abgelehnt werden, bevor die Organisation der Regel bestätigt ist (die oben genannte `400 invalid_request_error`-Familie), hinterlassen keinen Verlaufseintrag; ihre Antwortnachrichten benennen das Problem direkt. Ein `401` ohne passenden Verlaufseintrag bedeutet in der Regel, dass die `federation_rule_id` selbst nicht erkannt wurde. ### Häufige Fehler auf SDK-Seite | Symptom | Ursache | Lösung | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | SDK meldet „no credentials", anstatt einen Austausch 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 sich mit einem API-Key statt über Federation | `ANTHROPIC_API_KEY` oder `ANTHROPIC_AUTH_TOKEN` ist gesetzt und hat Vorrang. | Entferne die Key- oder Token-Variable mit unset. | | `FileNotFoundError` bei der ersten Anfrage | Der Pfad in `ANTHROPIC_IDENTITY_TOKEN_FILE` existiert nicht. Das SDK öffnet die Datei verzögert zum Zeitpunkt des Austauschs. | Bestätige, dass das Volume für das projizierte Token eingehängt ist und der Pfad übereinstimmt. | | Token-Austausch ist erfolgreich, 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 anhand der [OAuth-Scopes](https://platform.claude.com/docs/de/manage-claude/wif-reference#oauth-scopes). | | Authentifizierung schlägt mit leeren Anmeldedaten fehl | Eine Anmeldedaten-Umgebungsvariable ist exportiert, aber auf einen leeren String gesetzt. Leere Werte können trotzdem ihren Platz in der Rangfolge gewinnen. | Entferne die Variable mit `unset VAR` statt mit `VAR=""`. | ## Fehlerbehebung bei einem fehlgeschlagenen Austausch Eine `401` `authentication_error`-Antwort ist absichtlich undurchsichtig und ihre Meldung lautet immer `Authentication failed`; der Ablehnungsgrund wird im Authentifizierungsverlauf festgehalten, nicht in der Antwort. Beginne mit der [Seite zum Authentifizierungsverlauf](https://platform.claude.com/settings/workload-identity-federation?tab=history) in der Claude Console. Aktuelle Austauschversuche zeigen den ausgewerteten Issuer und die ausgewertete Regel, die geprüften JWT-Claims und welcher Validierungsschritt fehlgeschlagen ist, was die folgenden Prüfungen in der Regel überflüssig macht. Ein häufiger undurchsichtiger Fehler ist eine wiederverwendete Assertion: Eine Assertion mit einem `jti`-Claim kann [nur einmal ausgetauscht werden](https://platform.claude.com/docs/de/manage-claude/wif-reference#jwt-verification), daher wird ein Workload, der dasselbe JWT erneut sendet (eine Wiederholungsschleife oder eine Aktualisierung, die ein nicht rotiertes Token erneut einliest), beim zweiten Austausch abgelehnt. Die Seite zum Authentifizierungsverlauf zeigt diese Versuche mit dem Grund `jti_reused`; die Lösung besteht darin, für jeden Austausch eine neue Assertion auszustellen. Wenn du dennoch anhand des JWT selbst debuggen musst, arbeite diese Prüfungen der Reihe nach ab: 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 eines eventuellen abschließenden Schrägstrichs. Eine Abweichung bei einem einzigen Zeichen lässt die Überprüfung fehlschlagen. Der dekodierte `aud`-Claim muss den `audience`-Wert der Regel als exakte Übereinstimmung 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-Toleranzfensters. Wenn die Uhr des Workload-Hosts abgewichen ist, wird ein ansonsten gültiges Token abgelehnt. Rufe im `discovery`-Modus `/.well-known/openid-configuration` über öffentliches HTTPS auf Port 443 ab und bestätige, dass `jwks_uri` aufgelöst wird. Rufe bei `explicit_url` die JWKS-URL direkt ab. Bestätige bei `inline`, dass der Signaturschlüssel des Issuers seit der Registrierung der Schlüssel nicht rotiert wurde. Wenn der Issuer seinen Signaturschlüssel rotiert und sofort damit zu signieren begonnen hat, können Austauschvorgänge bis zu einer Minute lang fehlschlagen, während der JWKS-Cache von Anthropic aktualisiert wird. Siehe [Schlüsselrotation und Caching](https://platform.claude.com/docs/de/manage-claude/wif-reference#key-rotation-and-caching). ## JWKS-Quellmodi Wenn du einen Federation-Issuer registrierst, steuert das Feld `jwks`, wie Anthropic die öffentlichen Schlüssel bezieht, mit denen JWT-Signaturen dieses Issuers überprüft werden. Es handelt sich um eine diskriminierte Union mit `type` als Schlüssel: | `jwks.type` | `jwks`-Struktur | Verhalten | Verwenden, wenn | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `discovery` (Standard) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` ist optional; setze es, wenn sich die Discovery-URL von `issuer_url` unterscheidet) | 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 Anbieter (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-Claim `iss` verwendet und niemals aufgerufen. | Dein IdP stellt kein Discovery-Dokument bereit, oder Discovery ist nur intern verfügbar, das JWKS aber öffentlich erreichbar. | | `inline` | `{ "type": "inline", "keys": [...] }` | Du stellst das Array der JWK-Objekte inline bereit (das `keys`-Array aus dem JWKS-Dokument, nicht das umschließende 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 möchtest. | Die diskriminierte Union macht die zugehörigen Felder konstruktionsbedingt gegenseitig ausschließend. Sowohl `discovery` als auch `explicit_url` akzeptieren zusätzlich einen optionalen `ca_cert_pem`-String für Issuer, die TLS über eine private CA bereitstellen. ### Schlüsselrotation und Caching In den Modi `discovery` und `explicit_url` speichert Anthropic das abgerufene JWKS im Cache. Wenn dein Identitätsanbieter einen neuen Signaturschlüssel veröffentlicht und sofort beginnt, Tokens damit zu signieren, können Austauschvorgänge mit diesen Tokens bis zu 1 Minute lang mit einem Signaturfehler fehlschlagen, während der Cache aktualisiert wird. Um dieses Zeitfenster zu vermeiden, veröffentliche einen neuen Signaturschlüssel im JWKS mindestens 15 Minuten, bevor dein Identitätsanbieter beginnt, Tokens damit zu signieren, und behalte den abgelösten Schlüssel im JWKS, bis die damit signierten Tokens abgelaufen sind. Verwaltete Identitätsanbieter halten sich in der Regel von selbst an diese Vorgehensweise. Wenn du deinen eigenen Issuer betreibst (einen selbstverwalteten Kubernetes-Cluster, einen SPIRE-OIDC-Discovery-Provider oder einen benutzerdefinierten Okta-Autorisierungsserver mit konfiguriertem Rotationsrhythmus), stelle sicher, dass deine Rotationsrichtlinie neue Schlüssel vor ihrer ersten Verwendung veröffentlicht. Im `inline`-Modus gibt es keine automatische Schlüsselaktualisierung. Wenn dein Identitätsanbieter seine Signaturschlüssel rotiert, musst du die Issuer-Konfiguration mit dem neuen JWKS aktualisieren, sonst schlagen alle Token-Austauschvorgänge bei der Signaturüberprüfung fehl.