Workload Identity Federation

„Workload Identity Federation“ (Workload-Identitätsföderation), oder WIF, ermöglicht es deinen Workloads, sich gegenüber der Claude API mit kurzlebigen OpenID-Connect-Token (OIDC) anstelle von langlebigen sk-ant-... API-Keys zu authentifizieren. Die Token stammen von einem „identity provider“ (Identitätsanbieter), oder IdP, den du bereits betreibst: AWS IAM, Google Cloud oder ein beliebiger standardkonformer OIDC-Aussteller wie GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID oder Okta.

Dein Workload legt ein signiertes JWT deines Identitätsanbieters vor. Anthropic validiert es anhand von Vertrauensregeln, die du in der Claude Console konfigurierst, und gibt ein kurzlebiges Anthropic-Zugriffstoken zurück, das an ein Service-Konto in deiner Organisation gebunden ist. Es gibt keine statischen Geheimnisse, die erzeugt, in CI gespeichert, rotiert oder geleakt werden könnten.

Workload Identity Federation stärkt deine Sicherheitslage, indem statische API-Keys durch Token ersetzt werden, die in Minuten statt nie ablaufen. Für sich allein ist es keine vollständige Sicherheitslösung: Föderierte Authentifizierung ist nur so stark wie der vorgelagerte Identitätsanbieter, der das JWT signiert. Kombiniere Workload Identity Federation mit den Kontrollen, die dein IdP bereits unterstützt (Workload-Identitätsbindung, bedingter Zugriff, Audit-Logging), um eine mehrschichtige Verteidigung zu erreichen.

Konzepte

Du konfigurierst drei Ressourcen in der Claude Console, bevor ein Workload föderieren kann. Zusammen drücken sie aus: „Token, die von Aussteller X signiert sind und deren Claims wie Y aussehen, dürfen als Service-Konto Z agieren.“

Service-Konten

Ein „service account“ (Service-Konto) (svac_...) ist eine benannte, nicht-menschliche Identität innerhalb deiner Anthropic-Organisation. Es ist der Principal, als der ein Service-Konto-Key oder ein föderiertes Token agiert. Service-Konten existieren auf Organisationsebene und werden in einem Workspace aktiv, wenn du sie als Mitglieder dieses Workspace hinzufügst. Zum Zeitpunkt des Austauschs prüft Anthropic, dass der Workspace der Föderationsregel mit einer der Workspace-Mitgliedschaften des Service-Kontos übereinstimmt; das erzeugte Token folgt dann den Ratenlimits und der Nutzungszuordnung dieses Workspace, genau wie ein API-Key. Anders als ein menschlicher Benutzer hat ein Service-Konto keine E-Mail, kein Passwort und keinen Console-Login. Jedes Service-Konto ist implizit Mitglied des Standard-Workspace deiner Organisation; füge explizite Mitgliedschaften für jeden weiteren Workspace hinzu, in dem es agieren soll. Damit ein Service-Konto-Key für alle Workspaces in einem Workspace agieren kann, füge das Service-Konto diesem Workspace hinzu.

Der wesentliche Unterschied zu einem Workspace-API-Key: Ein Workspace-API-Key ist ein Credential, während ein Service-Konto Credentials hat. Du kannst leichter nachvollziehen, welche Workloads als welches Service-Konto agiert haben.

Föderationsaussteller

Ein „federation issuer“ (Föderationsaussteller) (fdis_...) registriert einen OIDC-Identitätsanbieter bei deiner Organisation. Die Registrierung eines Ausstellers teilt Anthropic mit: „JWTs, die von diesem Anbieter signiert sind, dürfen Workload-Identität für meine Organisation geltend machen.“

Ein Aussteller hat zwei Konfigurationsbestandteile:

• Aussteller-URL: Der exakte Wert des iss-Claims, der in den JWTs des Anbieters erscheint, zum Beispiel https://token.actions.githubusercontent.com oder https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• JWKS-Quelle: Wie Anthropic die öffentlichen Schlüssel zur Verifizierung von JWT-Signaturen abruft. Verwende discovery (den Standard) für jeden Anbieter, der /.well-known/openid-configuration unter seiner Aussteller-URL bereitstellt. Verwende explicit_url, um direkt auf einen JWKS-Endpunkt zu verweisen, oder inline, um den Schlüsselsatz für Aussteller hochzuladen, die nicht aus dem öffentlichen Internet erreichbar sind (zum Beispiel ein privater Kubernetes-Cluster).

Aussteller- und JWKS-URLs müssen https verwenden, auf Port 443 liegen und einen öffentlichen DNS-Hostnamen nutzen, der zu öffentlichen IP-Adressen auflöst; IP-Literale werden nicht akzeptiert. Diese Einschränkungen gelten nur für URLs, die Anthropic abruft; in den Modi explicit_url und inline wird die issuer_url als Zeichenkette verglichen und darf auf einen internen Hostnamen verweisen.

Typischerweise registrierst du einen Aussteller pro Umgebung: Dein Produktions-EKS-Cluster, dein Staging-Cluster und GitHub Actions sind drei separate Aussteller.

Föderationsregeln

Eine „federation rule“ (Föderationsregel) (fdrl_...) ist die Brücke zwischen einem Aussteller und einem Service-Konto: „Wenn ein JWT von Aussteller X Claims hat, die wie Y aussehen, erzeuge ein Token für Service-Konto Z mit Scope S.“

Eine Regel definiert Match-Bedingungen, ein Ziel sowie den Autorisierungs-Scope und die Token-Lebensdauer, die gelten, wenn die Regel zutrifft:

• Match: Die Bedingungen, die ein eingehendes JWT erfüllen muss. Du kannst auf ein subject_prefix matchen (zum Beispiel system:serviceaccount:prod:worker, oder mit einem abschließenden * für einen Präfix-Match), auf eine exakte audience, auf eine Map exakter Claim-Werte, auf einen CEL-condition-Ausdruck für komplexe Logik oder auf eine beliebige Kombination davon. Mindestens eines von subject_prefix, claims oder condition muss gesetzt sein, und alle konfigurierten Matcher müssen erfüllt sein, damit das JWT akzeptiert wird.
• Ziel: Das Service-Konto, auf das das gematchte JWT abgebildet wird.
• Autorisierung: Der OAuth-scope, der dem erzeugten Token gewährt wird. Der Standard ist workspace:developer, was denselben Zugriff wie ein Workspace-API-Key gewährt. Einige Produkte sperren den Scope, wenn du eine Regel aus ihrem Ablauf heraus erstellst; zum Beispiel erstellt das Create-Tunnel-Modal der MCP-Tunnel Regeln mit dem Scope workspace:manage_tunnels. Siehe OAuth-Scopes. Die Regel legt außerdem token_lifetime_seconds fest (60 bis 86400, Standard 3600).

Ein einzelner Aussteller kann viele Regeln haben: eine pro Team, Namespace oder Berechtigungsstufe. Regeln werden anhand ihrer ID ausgewertet: Der Client gibt in der Austauschanfrage an, welche Regel verwendet werden soll, und Anthropic verifiziert, dass das JWT die Match-Kriterien dieser Regel erfüllt. Es gibt keine implizite Regelsuche.

So funktioniert es

1. Dein IdP stellt dem Workload ein JWT aus. Auf den meisten Plattformen geschieht dies ambient: ein projiziertes Kubernetes-Service-Account-Token, der Google Cloud-Metadatenserver, Azure IMDS oder der GitHub Actions-OIDC-Endpunkt. Der iss-Claim des JWT identifiziert den Anbieter, und sein sub-Claim sowie weitere Claims identifizieren den konkreten Workload.
2. Das SDK tauscht das JWT gegen ein Anthropic-Zugriffstoken. Das SDK sendet das JWT per POST /v1/oauth/token unter Verwendung des jwt-bearer-Grants nach RFC 7523. Anthropic verifiziert das JWT anhand des JWKS des Ausstellers und der Match-Bedingungen der Föderationsregel und gibt dann ein kurzlebiges sk-ant-oat01-...-Token zurück, das im Namen des Ziel-Service-Kontos der Regel agiert.
3. Das SDK sendet das Token bei jeder Anfrage und erneuert es, bevor es abläuft. Dein Anwendungscode erstellt den Client ohne api_key und ruft die API wie gewohnt auf. Das SDK führt den Austausch erneut durch, bevor das Token abläuft.

Föderation einrichten

Du benötigst die Rolle Admin, Owner oder Primary Owner in deiner Anthropic-Organisation, einen OIDC-fähigen Identitätsanbieter mit einem erreichbaren JWKS-Endpunkt (oder ein JWKS-Dokument, das du einfügen kannst, für Air-Gapped-Cluster) sowie einen Workload, der ein Identitätstoken von diesem Anbieter beziehen kann.

Der Assistent Connect workload erstellt alle drei Ressourcen (den Aussteller, das Service-Konto und die Föderationsregel) in einem geführten Ablauf und verifiziert anschließend die Verbindung Ende-zu-Ende.

1. 1

   Connect workload öffnen

   Gehe in der Claude Console zu Settings → Workload identity und wähle Connect workload.

2. 2

   Deinen Anbieter auswählen

   Wähle die Kachel für deinen Identitätsanbieter: GitHub Actions, AWS, Google Cloud, Microsoft Entra ID oder Kubernetes. Jede Kachel füllt das Aussteller-URL-Muster und die Match-Felder vor, die die JWTs dieses Anbieters unterstützen. Für jeden anderen standardkonformen Anbieter (wie SPIFFE oder Okta) wähle Custom OIDC.

3. 3

   Die geführten Felder ausfüllen

   Der Assistent führt dich durch die anbieterspezifischen Felder: die Ausstellerkonfiguration, die Match-Bedingungen für eingehende JWTs sowie Namen für das Service-Konto und die Föderationsregel, die er erstellt. Der Assistent füllt oauth_scope=workspace:developer und token_lifetime_seconds=600 vor (der API-Standard, wenn token_lifetime_seconds weggelassen wird, ist 3600); passe diese an, wenn dein Workload einen anderen Scope oder eine andere Lebensdauer benötigt.

4. 4

   Den Aussteller verifizieren

   Wähle optional Verify issuer, um die Ausstellerkonfiguration probeweise zu prüfen, bevor etwas erstellt wird. Die Verifizierung bestätigt, dass Anthropic das JWKS von den eingegebenen URLs abrufen und parsen kann, wodurch Erreichbarkeits- und Konfigurationsfehler frühzeitig erkannt werden.

5. 5

   Die Verbindung testen

   Der Assistent erstellt den Aussteller, das Service-Konto und die Föderationsregel und wartet dann 15 Minuten lang auf einen erfolgreichen Token-Austausch. Löse innerhalb dieses Zeitfensters einen Austausch von deinem Workload aus (siehe Von deinem Workload aus authentifizieren), um zu bestätigen, dass die Einrichtung funktioniert. Wenn das Zeitfenster abläuft, bleiben die Ressourcen bestehen; du kannst den Test von der Detailseite der Föderationsregel aus erneut ausführen. Notiere dir die ID der Regel (fdrl_...) und die Service-Konto-ID (svac_...), die der Assistent erstellt: Dein Workload übergibt beide zusammen mit deiner Organisations-ID (und deiner Workspace-ID, wenn die Regel mehr als einen Workspace abdeckt) in jeder Token-Austauschanfrage.

Um diese Ressourcen programmatisch zu verwalten, siehe WIF mit der Admin API verwalten für die curl-Anleitung, oder siehe die API-Referenz für Service-Konten, die API-Referenz für Föderationsaussteller und die API-Referenz für Föderationsregeln für vollständige Parameterdetails und Antwortschemata.

Von deinem Workload aus authentifizieren

Sobald die Föderation konfiguriert ist, tauscht dein Workload zur Laufzeit sein vom IdP ausgestelltes JWT gegen ein Anthropic-Token. Die SDKs übernehmen den Austausch und die Erneuerungsschleife für dich. Der cURL-Tab zeigt den zugrunde liegenden HTTP-Austausch für Shell-Skripte, Debugging oder Sprachen ohne SDK-Unterstützung.

Den SDK-Client erstellen

Du kannst den Client mit expliziten Credentials oder ohne Argumente erstellen. Ohne Argumente löst das SDK Credentials aus Umgebungsvariablen oder dem aktiven Profil auf, wie unter Credential-Rangfolge beschrieben. Die Form ohne Argumente ist das empfohlene Muster für Produktions-Workloads: Liefere überall dasselbe Container-Image aus und injiziere ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID und ANTHROPIC_IDENTITY_TOKEN_FILE pro Umgebung.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Die Antwort des Token-Austauschs folgt RFC 6749 §5.1. Siehe Antwort des Token-Austauschs für die Feldreferenz.

Credential-Rangfolge

Jedes SDK löst Credentials in derselben fünfstufigen Reihenfolge auf: Konstruktorargumente, dann ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, dann ein explizites ANTHROPIC_PROFILE, dann die Föderations-Umgebungsvariablen, dann das implizite aktive Profil. Die erste Quelle, die ein Credential liefert, gewinnt.

Die vollständige Rangfolgetabelle, die Semantik der einzelnen Stufen und das Schema der Profildatei findest du unter Credential-Rangfolge in der WIF-Referenz.

Von API-Keys migrieren

So stellst du einen bestehenden Workload ohne Ausfallzeit von einem statischen API-Key auf Föderation um:

1. Föderation parallel konfigurieren. Schließe die Einrichtungsanleitung ab und bestätige, dass die Föderationsregel zum Token deines Workloads passt. Lass den bestehenden ANTHROPIC_API_KEY vorerst bestehen.
2. Per Smoke-Test prüfen, welches Credential gewinnt. Führe ant auth status innerhalb des Workloads aus (oder prüfe die SDK-Debug-Logs). Da ANTHROPIC_API_KEY in der Rangfolgekette über den Föderationsstufen steht, gewinnt der API-Key in dieser Phase noch.
3. ANTHROPIC_API_KEY überall entfernen, wo er injiziert wird. Entferne ihn aus CI-Secrets, der Container-Umgebung und Shell-Profilen (siehe die vorangehende Warnung). Führe ant auth status erneut aus und bestätige, dass nun die Föderationsquelle ausgewählt ist.
4. Den API-Key löschen. Sobald der Workload mit dem föderierten Token läuft, lösche den Key in der Claude Console unter Settings → API keys.

Token-Lebensdauer und Erneuerung

Die Lebensdauer des erzeugten Anthropic-Tokens ist der kleinere Wert aus (a) dem token_lifetime_seconds der Regel (Standard 3.600 Sekunden) und (b) dem Doppelten der verbleibenden Lebensdauer des vorgelegten IdP-JWT. Das Ergebnis beträgt nie weniger als 60 Sekunden. Die zweite Grenze verhindert, dass ein Anthropic-Token die vorgelagerte Identität, von der es abgeleitet wurde, um mehr als eine kleine Spanne überlebt.

Die SDKs cachen das Token und erneuern es nach einem zweistufigen Zeitplan, der botocore nachempfunden ist:

• Empfohlene Erneuerung bei Ablauf minus 120 Sekunden. Das SDK versucht einen neuen Austausch. Wenn der Token-Endpunkt nicht erreichbar ist, liefert das SDK weiterhin das gecachte Token aus, das noch etwa 90 weitere Sekunden gültig ist.
• Verpflichtende Erneuerung bei Ablauf minus 30 Sekunden. Ein fehlgeschlagener Austausch an diesem Punkt löst einen Fehler aus. Das gecachte Token ist zu nah am Ablauf, um sicher zu sein.

Da das SDK ANTHROPIC_IDENTITY_TOKEN_FILE bei jedem Austausch neu einliest, übernimmt es rotierte projizierte Token transparent (Kubernetes-Service-Account-Token rotieren zum Beispiel deutlich vor ihrem exp).

Standardmäßig sind Identitätstoken, die einen jti-Claim tragen, nur einmal verwendbar: Jeder Austausch muss ein JWT vorlegen, das zuvor noch nicht ausgetauscht wurde, und das erneute Vorlegen eines solchen schlägt mit dem Grund jti_reused auf der Seite mit dem Authentifizierungsverlauf fehl. Wenn dein Workload seine eigenen Token von deinem Identitätsanbieter abruft, erzeuge für jeden Austausch ein frisches JWT, anstatt ein gecachtes wiederzuverwenden (Retry-Schleifen sind der häufigste Verursacher). Dasselbe gilt für ein Token, das aus ANTHROPIC_IDENTITY_TOKEN_FILE gelesen wird: Das SDK liest die Datei bei jedem Austausch neu ein, daher muss die Datei vor jeder Erneuerung ein neues Token enthalten. Eine Erneuerung, die ein nicht rotiertes Token erneut einliest, oder ein neu gestarteter Prozess, der ein bereits ausgetauschtes Token erneut vorlegt, wird auf dieselbe Weise abgelehnt. Wenn du das Token deutlich innerhalb der Lebensdauer des erzeugten Tokens rotierst, bleibt die Datei dem Erneuerungszeitplan voraus; wenn deine Token-Quelle nicht so häufig rotieren kann, kannst du als letzten Ausweg check_jti für diesen Aussteller deaktivieren (dies entfernt den Replay-Schutz für jede Regel dieses Ausstellers). Siehe JWT-Verifizierung für Details.

Identitätsanbieter

Jeder Leitfaden behandelt, woher das JWT auf der jeweiligen Plattform stammt, wie seine Claims aussehen und welche Aussteller- und Regelkonfiguration zu registrieren ist.

Siehe auch

• WIF mit der Admin API verwalten: Aussteller, Service-Konten und Regeln per Infrastructure as Code erstellen
• WIF-Referenz: Umgebungsvariablen, Schema der Profildatei, Validierungsregeln und Fehlercodes
• Authentifizierung: alle Authentifizierungsoptionen in den Anthropic SDKs
• Admin-API-Referenz: generierte Anfrage- und Antwortschemata für jeden Admin-API-Endpunkt