Workload Identity Federation

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

Dein Workload präsentiert ein signiertes JWT von deinem Identitätsanbieter. 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 Secrets, die erstellt, in CI gespeichert, rotiert oder geleakt werden könnten.

Workload Identity Federation stärkt deine Sicherheitslage, indem statische API-Keys durch Tokens ersetzt werden, die in Minuten ablaufen statt nie. Es ist für sich genommen keine vollständige Sicherheitslösung: Die 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), für eine mehrschichtige Verteidigung.



Konzepte

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



Service-Konten

Ein Service-Konto (svac_...) ist eine benannte, nicht-menschliche Identität innerhalb deiner Anthropic-Organisation. Es ist der Principal, als der 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, ob der Workspace der Föderationsregel mit einer der Workspace-Mitgliedschaften des Service-Kontos übereinstimmt; das ausgestellte Token folgt dann den Ratenlimits und der Nutzungszuordnung dieses Workspace, genau wie ein API-Key. Im Gegensatz zu einem menschlichen 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 anderen Workspace hinzu, in dem es agieren soll.

Der wesentliche Unterschied zu einem API-Key: Ein API-Key ist eine Anmeldeinformation, während für ein Service-Konto bei Bedarf Anmeldeinformationen ausgestellt werden. Du kannst nachvollziehen, welche Workloads als welches Service-Konto agiert haben.



Föderations-Issuer

Ein Föderations-Issuer (fdis_...) registriert einen OIDC-Identitätsanbieter bei deiner Organisation. Die Registrierung eines Issuers teilt Anthropic mit: „JWTs, die von diesem Anbieter signiert wurden, dürfen Workload-Identität für meine Organisation geltend machen."

Ein Issuer hat zwei Konfigurationselemente:

• Issuer-URL: Der exakte iss-Claim-Wert, 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 abruft, um JWT-Signaturen zu verifizieren. Verwende discovery (die Standardeinstellung) für jeden Anbieter, der /.well-known/openid-configuration unter seiner Issuer-URL bereitstellt. Verwende explicit_url, um direkt auf einen JWKS-Endpunkt zu verweisen, oder inline, um das Key-Set für Issuer hochzuladen, die nicht aus dem öffentlichen Internet erreichbar sind (zum Beispiel ein privater Kubernetes-Cluster).

Issuer- und JWKS-URLs müssen https verwenden, auf Port 443 laufen und einen öffentlichen DNS-Hostnamen verwenden, 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 String verglichen und kann auf einen internen Hostnamen verweisen.

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



Föderationsregeln

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

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), eine exakte audience, eine Map exakter Claim-Werte, einen CEL-condition-Ausdruck für komplexe Logik oder 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.
• Target: Das Service-Konto, auf das das gematchte JWT abgebildet wird.
• Authorization: Der OAuth-scope, der dem ausgestellten Token gewährt wird. Der Standard ist workspace:developer, was denselben Zugriff gewährt wie ein für diesen Workspace ausgestellter API-Key. Einige Produkte sperren den Scope, wenn du eine Regel aus ihrem Flow 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 Issuer kann viele Regeln haben: eine pro Team, Namespace oder Berechtigungsstufe. Regeln werden anhand ihrer ID ausgewertet: Der Client gibt in der Exchange-Anfrage 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 automatisch: 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 sowie andere Claims identifizieren den spezifischen Workload.
2. Das SDK tauscht das JWT gegen ein Anthropic-Zugriffstoken aus. Das SDK sendet das JWT per POST an POST /v1/oauth/token unter Verwendung des jwt-bearer-Grants nach RFC 7523. Anthropic verifiziert das JWT anhand des JWKS des Issuers 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 konstruiert 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 abgeschottete Cluster) und einen Workload, der ein Identitäts-Token von diesem Anbieter abrufen kann.

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

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



Von deinem Workload aus authentifizieren

Wenn die Föderation konfiguriert ist, tauscht dein Workload zur Laufzeit sein vom IdP ausgestelltes JWT gegen ein Anthropic-Token aus. Die SDKs übernehmen den Austausch und die Refresh-Schleife 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 konstruieren

Du kannst den Client mit expliziten Anmeldeinformationen oder ohne Argumente konstruieren. Ohne Argumente löst das SDK Anmeldeinformationen aus Umgebungsvariablen oder dem aktiven Profil auf, wie unter Credential-Priorität 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Die Token-Exchange-Response folgt RFC 6749 §5.1. Siehe Token-Exchange-Response für die Feldreferenz.



Credential-Priorität

Jedes SDK löst Anmeldeinformationen in derselben fünfstufigen Reihenfolge auf: Konstruktor-Argumente, 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 eine Anmeldeinformation liefert, gewinnt.

Für die vollständige Prioritätstabelle, die Semantik pro Stufe und das Profildatei-Schema siehe Credential-Priorität in der WIF-Referenz.



Von API-Keys migrieren

Um einen bestehenden Workload ohne Ausfallzeit von einem statischen API-Key auf Föderation umzustellen:

1. Föderation parallel konfigurieren. Schließe die Einrichtungsanleitung ab und bestätige, dass die Föderationsregel auf das Token deines Workloads matcht. Lasse den bestehenden ANTHROPIC_API_KEY vorerst bestehen.
2. Per Smoke-Test prüfen, welche Anmeldeinformation gewinnt. Führe ant auth status innerhalb des Workloads aus (oder inspiziere die SDK-Debug-Logs). Da ANTHROPIC_API_KEY in der Prioritätskette ü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, Container-Umgebung und Shell-Profilen (siehe die vorangehende Warnung). Führe ant auth status erneut aus und bestätige, dass jetzt die Föderationsquelle ausgewählt wird.
4. Den API-Key widerrufen. 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 Refresh

Die Lebensdauer des ausgestellten Anthropic-Tokens ist der kleinere Wert von (a) den token_lifetime_seconds der Regel (Standard 3600 Sekunden) und (b) dem Doppelten der verbleibenden Lebensdauer des IdP-JWT, das du präsentiert hast. Das Ergebnis ist nie kleiner als 60 Sekunden. Die zweite Grenze verhindert, dass ein Anthropic-Token die vorgelagerte Identität, von der es abgeleitet wurde, um mehr als einen kleinen Spielraum überlebt.

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

• Advisory Refresh 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.
• Mandatory Refresh bei Ablauf minus 30 Sekunden. Ein fehlgeschlagener Austausch zu diesem Zeitpunkt 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 transparent rotierte projizierte Tokens (Kubernetes-Service-Account-Tokens rotieren beispielsweise deutlich vor ihrem exp).



Identitätsanbieter

Jeder Leitfaden behandelt, woher das JWT auf dieser Plattform kommt, wie seine Claims aussehen und welche Issuer- und Regelkonfiguration zu registrieren ist.



Siehe auch

• WIF mit der Admin API verwalten: Erstelle Issuer, Service-Konten und Regeln aus Infrastructure-as-Code
• WIF-Referenz: Umgebungsvariablen, Profildatei-Schema, Validierungsregeln und Fehlercodes
• Authentifizierung: Alle Authentifizierungsoptionen in den Anthropic-SDKs
• Admin-API-Referenz: Generierte Request- und Response-Schemas für jeden Admin-API-Endpunkt