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 « identity provider » (fournisseur d'identité), ou 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 de courte durée lié à un compte de service de votre organisation. Il n'y a aucun secret statique à générer, à stocker dans la CI, à faire tourner ou à laisser fuiter.

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 à elle seule : l'authentification fédérée n'est aussi robuste que le fournisseur d'identité en amont qui signe le JWT. Associez 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 « service account » (compte de service) (svac_...) est une identité nommée, non humaine, au sein de votre organisation Anthropic. C'est le principal au nom duquel agit une clé de compte de service ou un jeton fédéré. 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 à un 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 e-mail, ni mot de passe, ni 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. Pour permettre à une clé de compte de service couvrant tous les espaces de travail d'agir dans un espace de travail, ajoutez le compte de service à cet espace de travail.

La distinction clé par rapport à une clé API d'espace de travail : une clé API d'espace de travail est un identifiant, tandis qu'un compte de service possède des identifiants. Vous pouvez plus facilement auditer quelles charges de travail ont agi en tant que quel compte de service.

Émetteurs de fédération

Un « federation issuer » (é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 des 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 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 littéraux IP ne sont pas acceptés. 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 « federation rule » (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 un subject_prefix (par exemple, system:serviceaccount:prod:worker, ou avec un * final pour une correspondance par 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 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 : la scope OAuth 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 d'espace de travail. Certains produits verrouillent la portée lorsque vous créez une règle depuis leur parcours ; par exemple, la fenêtre modale de création de tunnel des tunnels MCP crée des règles avec la portée workspace:manage_tunnels. Consultez Portées OAuth. La règle définit également token_lifetime_seconds (de 60 à 86400, 3600 par défaut).

Un seul émetteur peut avoir de nombreuses règles : une par équipe, par espace de noms ou par niveau d'autorisation. 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 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 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-... 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 renouvelle avant son expiration. Le code de votre 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 d'un document JWKS que vous pouvez coller, pour les clusters isolés du réseau), et d'une charge de travail capable d'obtenir un jeton d'identité auprès 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 parcours guidé, puis vérifie la connexion de bout en bout.

1. 1

   Ouvrir Connect workload

   Dans la Claude Console, accédez à Settings → Workload identity et sélectionnez Connect workload.

2. 2

   Choisir votre fournisseur

   Sélectionnez la tuile correspondant à votre fournisseur d'identité : GitHub Actions, AWS, Google Cloud, Microsoft Entra ID ou Kubernetes. Chaque tuile préremplit le modèle d'URL d'émetteur et les champs de correspondance pris en charge par les JWT de ce fournisseur. Pour tout autre fournisseur conforme aux standards (tel que SPIFFE ou Okta), sélectionnez Custom OIDC.

3. 3

   Remplir les champs guidés

   L'assistant vous guide à travers les champs spécifiques au fournisseur : la configuration de l'émetteur, les conditions de correspondance pour les JWT entrants, et les noms du compte de service et de la règle de fédération qu'il crée. L'assistant préremplit oauth_scope=workspace:developer et token_lifetime_seconds=600 (la valeur par défaut de l'API lorsque token_lifetime_seconds est omis est 3600) ; ajustez ces valeurs si votre charge de travail nécessite une portée ou une durée de vie différente.

4. 4

   Vérifier l'émetteur

   Sélectionnez éventuellement Verify issuer pour tester à blanc la configuration de l'émetteur avant que quoi que ce soit ne soit créé. La vérification confirme qu'Anthropic peut récupérer et analyser le JWKS à partir des URL que vous avez saisies, ce qui permet de détecter tôt les erreurs d'accessibilité et de configuration.

5. 5

   Tester la connexion

   L'assistant crée l'émetteur, le compte de service et la règle de fédération, puis attend un échange de jeton réussi pendant 15 minutes. Déclenchez un échange depuis votre charge de travail dans cette fenêtre (consultez S'authentifier depuis votre charge de travail) pour confirmer que la configuration fonctionne. Si la fenêtre expire, les ressources persistent ; vous pouvez relancer le test depuis la page de détail de la règle de fédération. Notez l'ID de la règle (fdrl_...) et l'ID du compte de service (svac_...) créés par l'assistant : votre charge de travail transmet les deux, ainsi que l'ID de votre organisation (et l'ID de votre espace de travail lorsque la règle couvre plus d'un espace de travail), dans chaque requête d'échange de jeton.

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 à l'exécution. Les SDK gèrent pour vous l'échange et la boucle de renouvellement. L'onglet cURL montre l'échange HTTP sous-jacent pour les scripts shell, le débogage ou les langages sans prise en charge par un SDK.

Construire le client SDK

Vous pouvez construire le client avec des identifiants explicites ou sans argument. Sans argument, 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 de l'échange de jeton suit la RFC 6749 §5.1. Consultez Réponse de l'é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 de priorité complet, 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 de service :

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 l'ANTHROPIC_API_KEY existante en place pour le moment.
2. Testez rapidement 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 de 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 désormais sélectionnée.
4. Supprimez 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 renouvellement des jetons

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) le double de 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 borne empêche un jeton Anthropic de survivre à l'identité en amont dont il est dérivé au-delà d'une faible marge.

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

• Renouvellement indicatif à 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 reste valide pendant environ 90 secondes supplémentaires.
• Renouvellement 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 prend en compte 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).

Par défaut, les jetons d'identité qui portent une revendication jti sont à usage unique : chaque échange doit présenter un JWT qui n'a pas encore été échangé, et en présenter un à nouveau échoue avec le motif jti_reused sur la page d'historique d'authentification. Si votre charge de travail récupère ses propres jetons auprès de votre fournisseur d'identité, générez un nouveau JWT pour chaque échange au lieu de réutiliser un jeton en cache (les boucles de nouvelle tentative sont le coupable habituel). Il en va de même pour un jeton lu depuis ANTHROPIC_IDENTITY_TOKEN_FILE : le SDK relit le fichier à chaque échange, le fichier doit donc contenir un nouveau jeton avant chaque renouvellement. Un renouvellement qui relit un jeton non renouvelé, ou un processus redémarré qui présente à nouveau un jeton qu'il a déjà échangé, est rejeté de la même manière. Renouveler le jeton largement dans les limites de la durée de vie du jeton émis permet au fichier de rester en avance sur le calendrier de renouvellement ; si votre source de jetons ne peut pas effectuer de rotation aussi souvent, vous pouvez désactiver check_jti pour cet émetteur en dernier recours (cela supprime la protection contre la relecture pour toutes les règles de l'émetteur). Consultez Vérification des JWT pour plus de détails.

Fournisseurs d'identité

Chaque guide explique d'où provient le JWT sur cette plateforme, à quoi ressemblent 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éer des émetteurs, des comptes de service et des règles à partir de 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 dans 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