Workload Identity Federation

La « Workload Identity Federation » (fédération d'identité de charge de travail), ou WIF, permet à vos charges de travail de s'authentifier auprès de l'API Claude avec des jetons OpenID Connect (OIDC) de courte durée au lieu de clés API sk-ant-... de longue durée. Les jetons proviennent d'un fournisseur d'identité (IdP) que vous exploitez déjà : AWS IAM, Google Cloud, ou tout émetteur OIDC conforme aux normes tel que GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID ou Okta.

Votre charge de travail présente un JWT signé par votre fournisseur d'identité. Anthropic le valide par rapport aux règles de confiance que vous configurez dans la Claude Console et renvoie un jeton d'accès Anthropic de courte durée lié à un compte de service dans votre organisation. Il n'y a aucun secret statique à émettre, à stocker dans la CI, à faire tourner ou à divulguer.

La Workload Identity Federation renforce votre posture de sécurité en remplaçant les clés API statiques par des jetons qui expirent en quelques minutes plutôt que jamais. Ce n'est pas une solution de sécurité complète en soi : l'authentification fédérée n'est aussi solide que le fournisseur d'identité en amont qui signe le JWT. Associez la Workload Identity Federation aux contrôles que votre IdP prend déjà en charge (liaison d'identité de charge de travail, accès conditionnel, journalisation d'audit) pour une défense en profondeur.



Concepts

Vous configurez trois ressources dans la Claude Console avant qu'une charge de travail puisse se fédérer. Ensemble, elles expriment « les jetons signés par l'émetteur X, avec des revendications qui ressemblent à Y, peuvent agir en tant que compte de service Z ».



Comptes de service

Un compte de service (svac_...) est une identité non humaine nommée au sein de votre organisation Anthropic. C'est le principal en tant que lequel un jeton fédéré agit. Les comptes de service existent au niveau de l'organisation et deviennent actifs dans un espace de travail lorsque vous les ajoutez en tant que membres de cet espace de travail. Au moment de l'échange, Anthropic vérifie que l'espace de travail de la règle de fédération correspond à l'une des appartenances d'espace de travail du compte de service ; le jeton émis suit ensuite les limites de débit et l'attribution d'utilisation de cet espace de travail, de la même manière qu'une clé API. Contrairement à un utilisateur humain, un compte de service n'a pas d'e-mail, pas de mot de passe et pas de connexion à la Console. Chaque compte de service est implicitement membre de l'espace de travail par défaut de votre organisation ; ajoutez des appartenances explicites pour tout autre espace de travail dans lequel il doit agir.

La distinction clé par rapport à une clé API : une clé API est un identifiant, tandis qu'un compte de service a des identifiants émis pour lui à la demande. Vous pouvez auditer quelles charges de travail ont agi en tant que quel compte de service.



Émetteurs de fédération

Un émetteur de fédération (fdis_...) enregistre un fournisseur d'identité OIDC auprès de votre organisation. Enregistrer un émetteur indique à Anthropic « les JWT signés par ce fournisseur peuvent affirmer l'identité de charge de travail pour mon organisation ».

Un émetteur a deux éléments de configuration :

• URL de l'émetteur : La valeur exacte de la revendication iss qui apparaît dans les JWT du fournisseur, par exemple https://token.actions.githubusercontent.com ou https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Source JWKS : La manière dont Anthropic récupère les clés publiques pour vérifier les signatures JWT. Utilisez discovery (la valeur par défaut) pour tout fournisseur qui sert /.well-known/openid-configuration à son URL d'émetteur. Utilisez explicit_url pour pointer directement vers un point de terminaison JWKS, ou inline pour téléverser l'ensemble de clés pour les émetteurs qui ne sont pas accessibles depuis l'internet public (par exemple, un cluster Kubernetes privé).

Les URL d'émetteur et de JWKS doivent être en https, sur le port 443, et utiliser un nom d'hôte DNS public qui se résout en adresses IP publiques ; les adresses IP littérales ne sont pas acceptées. Ces contraintes s'appliquent uniquement aux URL qu'Anthropic récupère ; dans les modes explicit_url et inline, l'issuer_url est comparée en tant que chaîne de caractères et peut référencer un nom d'hôte interne.

Vous enregistrez généralement un émetteur par environnement : votre cluster EKS de production, votre cluster de préproduction et GitHub Actions sont trois émetteurs distincts.



Règles de fédération

Une règle de fédération (fdrl_...) est le pont entre un émetteur et un compte de service : « lorsqu'un JWT de l'émetteur X a des revendications qui ressemblent à Y, émettre un jeton pour le compte de service Z avec la portée S ».

Une règle définit des conditions de correspondance, une cible, ainsi que la portée d'autorisation et la durée de vie du jeton qui s'appliquent lorsque la règle correspond :

• Correspondance : Les conditions qu'un JWT entrant doit satisfaire. Vous pouvez faire correspondre sur un subject_prefix (par exemple, system:serviceaccount:prod:worker, ou avec un * final pour une correspondance de préfixe), une audience exacte, une carte de valeurs de revendications exactes, une expression condition CEL pour une logique complexe, ou toute combinaison. Au moins l'un de subject_prefix, claims ou condition doit être défini, et tous les critères de correspondance configurés doivent être satisfaits pour que le JWT soit accepté.
• Cible : Le compte de service auquel le JWT correspondant est associé.
• Autorisation : Le scope OAuth accordé sur le jeton émis. La valeur par défaut est workspace:developer, qui accorde le même accès qu'une clé API émise pour cet espace de travail. Certains produits verrouillent la portée lorsque vous créez une règle depuis leur flux ; par exemple, la fenêtre modale de création de tunnel des tunnels MCP crée des règles limitées à workspace:manage_tunnels. Consultez Portées OAuth. La règle définit également token_lifetime_seconds (60 à 86400, 3600 par défaut).

Un seul émetteur peut avoir de nombreuses règles : une par équipe, espace de noms ou niveau de permission. Les règles sont évaluées par ID : le client spécifie quelle règle utiliser dans la requête d'échange, et Anthropic vérifie que le JWT satisfait les critères de correspondance de cette règle. Il n'y a pas de recherche de règle implicite.



Fonctionnement

1. Votre IdP émet un JWT pour la charge de travail. Sur la plupart des plateformes, cela est ambiant : un jeton de compte de service projeté Kubernetes, le serveur de métadonnées Google Cloud, Azure IMDS, ou le point de terminaison OIDC de GitHub Actions. La revendication iss du JWT identifie le fournisseur, et ses revendications sub et autres identifient la charge de travail spécifique.
2. Le SDK échange le JWT contre un jeton d'accès Anthropic. Le SDK envoie le JWT à POST /v1/oauth/token en utilisant le grant jwt-bearer de la RFC 7523. Anthropic vérifie le JWT par rapport au JWKS de l'émetteur et aux conditions de correspondance de la règle de fédération, puis renvoie un jeton sk-ant-oat01-... de courte durée qui agit au nom du compte de service cible de la règle.
3. Le SDK envoie le jeton à chaque requête et le rafraîchit avant son expiration. Votre code d'application construit le client sans api_key et appelle l'API comme d'habitude. Le SDK relance l'échange avant l'expiration du jeton.



Configurer la fédération

Vous avez besoin du rôle admin, owner ou primary owner dans votre organisation Anthropic, d'un fournisseur d'identité compatible OIDC avec un point de terminaison JWKS accessible (ou un document JWKS que vous pouvez coller, pour les clusters isolés), et d'une charge de travail qui peut obtenir un jeton d'identité de ce fournisseur.

L'assistant Connect workload crée les trois ressources (l'émetteur, le compte de service et la règle de fédération) en un seul flux guidé, puis vérifie la connexion de bout en bout.

Pour gérer ces ressources par programmation, consultez Gérer WIF avec l'Admin API pour le guide pas à pas avec curl, ou consultez la référence de l'API des comptes de service, la référence de l'API des émetteurs de fédération et la référence de l'API des règles de fédération pour les détails complets des paramètres et les schémas de réponse.



S'authentifier depuis votre charge de travail

Une fois la fédération configurée, votre charge de travail échange son JWT émis par l'IdP contre un jeton Anthropic au moment de l'exécution. Les SDK gèrent l'échange et la boucle de rafraîchissement pour vous. L'onglet cURL montre l'échange HTTP sous-jacent pour les scripts shell, le débogage ou les langages sans prise en charge du SDK.



Construire le client SDK

Vous pouvez construire le client avec des identifiants explicites ou sans arguments. Sans arguments, le SDK résout les identifiants à partir des variables d'environnement ou du profil actif, comme décrit dans Priorité des identifiants. La forme sans argument est le modèle recommandé pour les charges de travail de production : déployez la même image de conteneur partout et injectez ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID et ANTHROPIC_IDENTITY_TOKEN_FILE par environnement.

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"))

La réponse d'échange de jeton suit la RFC 6749 §5.1. Consultez Réponse d'échange de jeton pour la référence des champs.



Priorité des identifiants

Chaque SDK résout les identifiants dans le même ordre à cinq niveaux : les arguments du constructeur, puis ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, puis un ANTHROPIC_PROFILE explicite, puis les variables d'environnement de fédération, puis le profil actif implicite. La première source qui fournit un identifiant l'emporte.

Pour le tableau complet de priorité, la sémantique de chaque niveau et le schéma du fichier de profil, consultez Priorité des identifiants dans la référence WIF.



Migrer depuis les clés API

Pour faire passer une charge de travail existante d'une clé API statique à la fédération sans interruption :

1. Configurez la fédération en parallèle. Suivez le guide de configuration et confirmez que la règle de fédération correspond au jeton de votre charge de travail. Laissez la ANTHROPIC_API_KEY existante en place pour le moment.
2. Testez quel identifiant l'emporte. Exécutez ant auth status depuis l'intérieur de la charge de travail (ou inspectez les journaux de débogage du SDK). Comme ANTHROPIC_API_KEY se situe au-dessus des niveaux de fédération dans la chaîne de priorité, la clé API l'emporte encore à ce stade.
3. Supprimez ANTHROPIC_API_KEY partout où elle est injectée. Retirez-la des secrets CI, de l'environnement du conteneur et des profils shell (voir l'avertissement précédent). Relancez ant auth status et confirmez que la source de fédération est maintenant sélectionnée.
4. Révoquez la clé API. Une fois que la charge de travail fonctionne avec le jeton fédéré, supprimez la clé dans la Claude Console sous Settings → API keys.



Durée de vie et rafraîchissement du jeton

La durée de vie du jeton Anthropic émis est la plus petite valeur entre (a) le token_lifetime_seconds de la règle (3 600 secondes par défaut) et (b) deux fois la durée de vie restante du JWT de l'IdP que vous avez présenté. Le résultat n'est jamais inférieur à 60 secondes. La seconde limite empêche un jeton Anthropic de survivre à l'identité en amont dont il a été dérivé de plus d'une petite marge.

Les SDK mettent le jeton en cache et le rafraîchissent selon un calendrier à deux niveaux inspiré de botocore :

• Rafraîchissement consultatif à l'expiration moins 120 secondes. Le SDK tente un nouvel échange. Si le point de terminaison de jeton est inaccessible, le SDK continue de servir le jeton en cache, qui est encore valide pendant environ 90 secondes supplémentaires.
• Rafraîchissement obligatoire à l'expiration moins 30 secondes. Un échange échoué à ce stade lève une erreur. Le jeton en cache est trop proche de l'expiration pour être sûr.

Comme le SDK relit ANTHROPIC_IDENTITY_TOKEN_FILE à chaque échange, il récupère de manière transparente les jetons projetés qui ont été renouvelés (les jetons de compte de service Kubernetes, par exemple, sont renouvelés bien avant leur exp).



Fournisseurs d'identité

Chaque guide couvre la provenance du JWT sur cette plateforme, l'apparence de ses revendications, ainsi que la configuration de l'émetteur et de la règle à enregistrer.



Voir aussi

• Gérer WIF avec l'Admin API : créez des émetteurs, des comptes de service et des règles depuis l'infrastructure en tant que code
• Référence WIF : variables d'environnement, schéma du fichier de profil, règles de validation et codes d'erreur
• Authentification : toutes les options d'authentification à travers les SDK Anthropic
• Référence de l'Admin API : schémas de requête et de réponse générés pour chaque point de terminaison de l'Admin API