Workload Identity Federation

Workload Identity Federation (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 ein beliebiger standardkonformer OIDC-Issuer wie GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID oder Okta.

Dein Workload präsentiert ein signiertes JWT von deinem Identity Provider. 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önnen.

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: Föderierte Authentifizierung ist nur so stark wie der vorgelagerte Identity Provider, der das JWT signiert. Kombiniere Workload Identity Federation mit den Kontrollen, die dein IdP bereits unterstützt (Workload-Identity-Binding, Conditional Access, 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, mit Claims, 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, dass der Workspace der Federation-Regel 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 ein Credential, während für ein Service-Konto Credentials bei Bedarf ausgestellt werden. Du kannst nachvollziehen, welche Workloads als welches Service-Konto agiert haben.



Federation-Issuer

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

Ein Issuer hat zwei Konfigurationsbestandteile:

• Issuer-URL: Der exakte Wert des iss-Claims, der in den JWTs des Providers 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 (der Standard) für jeden Provider, 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.



Federation-Regeln

Eine Federation-Regel (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. Mindestens eines von subject_prefix, claims oder condition muss gesetzt sein, und alle konfigurierten Matcher müssen bestehen, damit das JWT akzeptiert wird.
• Ziel: Das Service-Konto, auf das das gematchte JWT abgebildet wird.
• Autorisierung: Der OAuth-scope, der auf 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 legen den Scope fest, wenn du eine Regel aus ihrem Flow 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 Issuer kann viele Regeln haben: eine pro Team, Namespace oder Berechtigungsstufe. Regeln werden per 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 Metadata-Server, Azure IMDS oder der GitHub Actions OIDC-Endpunkt. Der iss-Claim des JWT identifiziert den Provider, und seine sub- und anderen Claims identifizieren den spezifischen Workload.
2. Das SDK tauscht das JWT gegen ein Anthropic-Zugriffstoken. 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 Federation-Regel 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 aus, bevor das Token abläuft.



Federation einrichten

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

Der Connect workload-Assistent erstellt alle drei Ressourcen (den Issuer, das Service-Konto und die Federation-Regel) in einem geführten Flow 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, die Federation-Issuer-API-Referenz und die Federation-Regeln-API-Referenz für vollständige Parameterdetails und Antwortschemata.



Von deinem Workload authentifizieren

Mit konfigurierter Federation tauscht dein Workload sein vom IdP ausgestelltes JWT zur Laufzeit gegen ein Anthropic-Token. 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.



SDK-Client konstruieren

Du kannst den Client mit expliziten Credentials oder ohne Argumente konstruieren. 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 Token-Austausch-Antwort folgt RFC 6749 §5.1. Siehe Token-Austausch-Antwort für die Feldreferenz.



Credential-Rangfolge

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

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



Von API-Keys migrieren

Um einen bestehenden Workload ohne Ausfallzeit von einem statischen API-Key auf Federation umzustellen:

1. Konfiguriere Federation parallel. Schließe die Einrichtungsanleitung ab und bestätige, dass die Federation-Regel auf das Token deines Workloads passt. Lasse den bestehenden ANTHROPIC_API_KEY vorerst an Ort und Stelle.
2. Teste, 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 Federation-Stufen steht, gewinnt der API-Key in diesem Stadium 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 vorstehende Warnung). Führe ant auth status erneut aus und bestätige, dass jetzt die Federation-Quelle ausgewählt wird.
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 ausgestellten Anthropic-Tokens ist das Minimum aus (a) den token_lifetime_seconds der Regel (Standard 3.600 Sekunden) und (b) dem Doppelten der verbleibenden Lebensdauer des IdP-JWT, das du präsentiert hast. Das Ergebnis ist 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:

• 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 zum Beispiel deutlich vor ihrem exp).



Identity Provider

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 über die Anthropic SDKs hinweg
• Admin-API-Referenz: generierte Anfrage- und Antwortschemata für jeden Admin-API-Endpunkt