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) à courte durée de vie plutôt qu'avec des clés API sk-ant-... à longue durée de vie. Les jetons proviennent d'un fournisseur d'identité (IdP) que vous exploitez déjà : AWS IAM, Google Cloud, ou tout émetteur OIDC conforme aux standards 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 à courte durée de vie lié à un compte de service dans votre organisation. Il n'y a aucun secret statique à générer, à stocker dans la CI, à faire tourner ou à exposer à des fuites.

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 robuste 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 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é nommée et non humaine au sein de votre organisation Anthropic. C'est le principal au nom duquel 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 comme 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 alors 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 ni adresse e-mail, ni mot de passe, ni accès à la Console.

La distinction clé avec une clé API : une clé API est un identifiant, tandis qu'un compte de service se voit émettre des identifiants à 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 une identité de charge de travail pour mon organisation ».

Un émetteur comporte 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 le jeu 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 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 littéraux IP ne sont pas acceptés. Ces contraintes s'appliquent uniquement aux URL qu'Anthropic récupère ; en 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 table de valeurs de revendications exactes, une expression condition CEL pour une logique complexe, ou toute combinaison de ces éléments. Au moins l'un des éléments 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 : La portée OAuth scope accordée 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 avec la portée org:manage_tunnels. Consultez Portées OAuth. La règle définit également token_lifetime_seconds (de 60 à 86400, 3600 par défaut).

Un même é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 implicite de règle.

Fonctionnement

1. Votre IdP émet un JWT à 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 sa revendication sub ainsi que d'autres revendications 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-... à courte durée de vie 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 applicatif 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 d'un accès administrateur à 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 capable d'obtenir un jeton d'identité auprès de ce fournisseur.

Dans la Claude Console, accédez à Settings → Workload identity.

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 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 sous 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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 : 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 par 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 de service :

1. Configurez la fédération en parallèle. Complétez la procédure de configuration et confirmez que la règle de fédération correspond au jeton de votre charge de travail. Laissez la variable ANTHROPIC_API_KEY existante en place pour l'instant.
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 de 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 (3600 secondes par défaut) et (b) le double de la durée de vie restante du JWT 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 est dérivé de plus qu'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 mis en cache, qui reste 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 mis 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 renouvelés (les jetons de compte de service Kubernetes, par exemple, sont renouvelés bien avant leur exp).

Fournisseurs d'identité

Chaque guide explique d'où provient le JWT sur cette plateforme, à quoi ressemblent ses revendications, et la configuration d'émetteur et de règle à enregistrer.

Voir aussi

• 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 dans les SDK Anthropic