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" (OIDC)-Tokens 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 der 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 sind 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 Workspaces 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 erstellte Token folgt dann den Ratenlimits und der Nutzungszuordnung dieses Workspaces, genau wie ein API-Key. Im Gegensatz zu einem menschlichen Benutzer hat ein Service-Konto keine E-Mail, kein Passwort und keinen Console-Login.

Der wesentliche Unterschied zu einem API-Key: Ein API-Key ist eine Anmeldeinformation, während für ein Service-Konto bei Bedarf Anmeldeinformationen erstellt 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 sind, 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 zur Verifizierung der JWT-Signaturen abruft. 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 hochzuladen, wenn Issuer 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, erstelle 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), eine exakte audience, eine Map exakter Claim-Werte, einen CEL-condition-Ausdruck für komplexe Logik oder eine beliebige Kombination. 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 erstellten 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 org: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 nach 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 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 RFC 7523 jwt-bearer-Grants. 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 Admin-Zugriff auf deine 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 erhalten kann.

Gehe in der Claude Console zu Settings → Workload identity.

Von deinem Workload aus authentifizieren

Mit konfigurierter Föderation 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-Austausch-Antwort folgt RFC 6749 §5.1. Siehe Token-Austausch-Antwort 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.

Die vollständige Prioritätstabelle, die Semantik pro Stufe und das Profildatei-Schema findest du unter Credential-Priorität 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. Konfiguriere die Föderation parallel. Führe die Einrichtungsanleitung durch und bestätige, dass die Föderationsregel auf das Token deines Workloads matcht. Lasse den bestehenden ANTHROPIC_API_KEY vorerst bestehen.
2. Teste per Smoke-Test, 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. Entferne ANTHROPIC_API_KEY überall dort, 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. Widerrufe den API-Key. 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 erstellten 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 liest, übernimmt es rotierte projizierte Tokens transparent (Kubernetes-Service-Account-Tokens rotieren zum Beispiel deutlich vor ihrem exp).

Identitätsanbieter

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

Siehe auch

• WIF-Referenz: Umgebungsvariablen, Profildatei-Schema, Validierungsregeln und Fehlercodes
• Authentifizierung: alle Authentifizierungsoptionen in den Anthropic-SDKs