Référence WIF

Cette page rassemble les surfaces de configuration, les contraintes de validation et les correspondances d'erreurs pour Workload Identity Federation. Pour des guides de configuration pas à pas, consultez les guides par fournisseur.

Requête d'échange de jeton

POST /v1/oauth/token accepte un corps JSON utilisant le type d'octroi jwt-bearer de la RFC 7523. Les SDK construisent cette requête pour vous à partir des variables d'environnement ; les exemples cURL de chaque guide de fournisseur montrent le corps brut.

Champ	Requis	Description
`grant_type`	Oui	Toujours `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Oui	Le JWT OIDC émis par votre fournisseur d'identité.
`federation_rule_id`	Oui	ID étiqueté (`fdrl_...`) de la règle de fédération à évaluer.
`organization_id`	Oui	UUID de votre organisation Anthropic.
`service_account_id`	Oui	ID étiqueté (`svac_...`) du compte de service cible.
`workspace_id`	Conditionnel	ID étiqueté (`wrkspc_...`) de l'espace de travail auquel restreindre le jeton émis, ou le littéral `default` pour l'espace de travail par défaut de l'organisation. Requis lorsque la règle est activée pour plus d'un espace de travail. En cas d'omission, le serveur sélectionne l'unique espace de travail activé de la règle.

Réponse d'échange de jeton

POST /v1/oauth/token renvoie une réponse de jeton OAuth 2.0 standard (RFC 6749 §5.1) :

Champ	Type	Description
`access_token`	string	Le jeton Anthropic de courte durée, préfixé par `sk-ant-oat01-...`. Passez-le sous la forme `Authorization: Bearer <token>`.
`token_type`	string	Toujours `Bearer`.
`expires_in`	integer	Nombre de secondes avant l'expiration du jeton.
`scope`	string	La portée OAuth accordée par la règle correspondante.

Variables d'environnement

Le SDK lit ces variables pour effectuer un échange de jeton fédéré sans arguments de constructeur.

Variable	Requise	Description	Exemple
`ANTHROPIC_FEDERATION_RULE_ID`	Oui	ID étiqueté de la règle de fédération à évaluer.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Oui	UUID de votre organisation Anthropic. Vous le trouverez dans la Claude Console sous Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	L'une de `_TOKEN_FILE` ou `_TOKEN`	Chemin du système de fichiers vers le JWT émis par votre fournisseur d'identité (IdP). Le SDK relit ce fichier à chaque échange afin que les jetons projetés qui sont renouvelés sur disque soient toujours à jour.	`/var/run/secrets/anthropic.com/token`

Le chemin de fédération direct par variables d'environnement ne s'active que lorsque ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID et l'une de ANTHROPIC_IDENTITY_TOKEN_FILE ou ANTHROPIC_IDENTITY_TOKEN sont toutes définies. ANTHROPIC_WORKSPACE_ID est lue en parallèle mais ne conditionne pas l'activation.

Une variable définie sur une chaîne vide occupe tout de même son emplacement dans la chaîne de priorité des identifiants. Si ANTHROPIC_API_KEY="" est exportée, le SDK sélectionne le chemin de la clé API avec une clé vide au lieu de passer à la fédération. Supprimez les variables d'identifiants inutilisées plutôt que de les vider.

Priorité des identifiants

Le SDK résout les identifiants dans cet ordre. La première source qui fournit un identifiant l'emporte.

Ordre	Source	Remarques
1	Argument du constructeur (`api_key=`, `auth_token=`, `credentials=`)	Prévaut toujours sur tout le reste.
2	`ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`	Masque entièrement la fédération. Supprimez-les lors de la migration depuis des clés API.
3	`ANTHROPIC_PROFILE`	Charge `<config_dir>/configs/<name>.json`. Un profil nommé manquant est une erreur, pas un passage à la source suivante.
4	Variables d'environnement de fédération	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + + .

Lorsqu'un profil est chargé, les variables d'environnement remplissent les champs que le profil omet mais ne remplacent jamais les champs que le profil définit explicitement. Par exemple, ANTHROPIC_WORKSPACE_ID remplit workspace_id uniquement lorsque le profil actif ne le définit pas.

Fichier de configuration de profil

Un profil est un fichier de configuration nommé que le SDK et la CLI ant lisent tous deux. Les profils vous permettent d'embarquer les paramètres de fédération avec votre image de conteneur ou de basculer entre les environnements sans modifier le code.

Répertoire de configuration

Le SDK localise le répertoire de configuration dans cet ordre :

$ANTHROPIC_CONFIG_DIR
~/.config/anthropic sur Linux et macOS
%APPDATA%\Anthropic sur Windows

Profil actif

Le nom du profil actif est résolu dans cet ordre :

$ANTHROPIC_PROFILE
Le contenu de <config_dir>/active_config (un fichier d'une seule ligne écrit par ant profile activate <name>)
Le nom littéral default

Claude Code et le Claude Agent SDK respectent ce même ordre de résolution, de sorte qu'un profil de fédération configuré ici authentifie également ces outils sans configuration supplémentaire.

Disposition des fichiers

Chemin	Contenu	Sensibilité
`<config_dir>/configs/<profile>.json`	`version`, le bloc `authentication`, `organization_id`, `workspace_id` et `base_url`.	Non secret. Peut être commité ou intégré dans une image en toute sécurité.
`<config_dir>/credentials/<profile>.json`	`version`, l'`access_token` mis en cache, `expires_at` et (pour la connexion interactive) `refresh_token`.	Secret. Écrit par le SDK avec le mode `0600`.

Le fichier de configuration et le fichier d'identifiants comportent tous deux un champ de chaîne version de premier niveau au format major.minor (actuellement "1.0"). Le SDK écrit ce champ automatiquement afin que les versions futures puissent détecter et migrer les formats plus anciens ; omettez-le lorsque vous rédigez une configuration à la main et le SDK traite le fichier comme étant à la version actuelle.

Exemple de profil de fédération

configs/production.json

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Si authentication.identity_token est omis, le SDK se rabat sur ANTHROPIC_IDENTITY_TOKEN_FILE ou ANTHROPIC_IDENTITY_TOKEN depuis l'environnement.

Portées OAuth

La valeur oauth_scope que vous définissez sur une règle de fédération détermine quels points de terminaison de l'API Claude le jeton d'accès émis peut appeler.

Portée	Donne accès à
`workspace:developer`	Tous les points de terminaison non administratifs de l'API Claude dans l'espace de travail de la règle : Messages (y compris le streaming et le comptage de jetons), Models, Managed Agents et leurs sessions, Files et Skills. Cela correspond à l'accès dont dispose une clé API émise pour le même espace de travail.
`org:manage_tunnels`	L'API des tunnels MCP : lister et obtenir des tunnels, enregistrer et archiver des certificats d'autorité de certification, révéler et faire tourner le jeton de tunnel, et archiver des tunnels. La fenêtre modale de création de tunnel de la Console verrouille cette portée lorsque vous créez une règle depuis celle-ci.

Une requête vers un point de terminaison hors de la portée du jeton renvoie HTTP 403. Des portées plus fines (par ressource, ou lecture versus écriture) ne sont pas disponibles actuellement.

Règles de validation

Anthropic applique ces contraintes lorsque vous créez ou mettez à jour des émetteurs et des règles, et lors de la vérification d'un JWT entrant au moment de l'échange.

Champs de ressource

Champ	Contrainte
`name` de l'émetteur, de la règle et du compte de service	Doit correspondre à `^[a-z0-9-]+$`, longueur de 1 à 255 caractères.
`workspace_id`	Facultatif. L'espace de travail (`wrkspc_...`) dont le quota, la facturation et les limites de débit s'appliquent aux jetons émis sous cette règle. Doit être un espace de travail de la même organisation, et le compte de service cible doit être membre de cet espace de travail. Peut être omis pour les règles configurées pour un seul espace de travail.
`token_lifetime_seconds`	Entier compris entre `60` et `86400` (1 minute à 24 heures). Valeur par défaut `3600`. Les valeurs hors de cette plage sont rejetées au moment de la requête. Voir Durée de vie et actualisation du jeton.

Champs d'URL

Les champs issuer_url, jwks.discovery_base et jwks.url sont validés :

Contrainte	Détail
Schéma	Doit être `https`.
Port	Doit être `443` (explicite ou par défaut).
Hôte	Doit être un nom d'hôte DNS public pour votre fournisseur OIDC. Doit se résoudre en adresses IP publiques ; les littéraux IP ne sont pas acceptés.

Les échecs de validation d'URL renvoient 400 invalid_request_error avec le nom du champ en préfixe du message d'erreur (par exemple, issuer_url: url must use https scheme).

Les contraintes d'URL s'appliquent uniquement aux URL qu'Anthropic contacte. Dans les modes JWKS explicit_url et inline, et dans le mode discovery lorsque jwks.discovery_base est défini, l'issuer_url est comparée à la revendication iss du JWT en tant que chaîne et n'est jamais récupérée, elle peut donc référencer un nom d'hôte interne ou un port non standard.

Vérification du JWT

Contrainte	Détail
Taille maximale	Le JWT `assertion` doit faire au plus 16 Kio.
Algorithme de signature	Seuls les algorithmes asymétriques (familles RSA et ECDSA : ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512) sont acceptés. HMAC (`HS256`, `HS384`, `HS512`) et `none` sont rejetés.
ID de clé	L'en-tête du JWT doit comporter un `kid` qui correspond à une clé dans le JWKS de l'émetteur. Les jetons sans `kid` sont rejetés.
Revendications requises	`sub` doit être présent. `iat` doit être présent et ne pas être dans le futur. `exp` doit être présent et dans le futur.
Durée de vie maximale

Sémantique de correspondance des règles

Le bloc match d'une règle de fédération détermine si un JWT entrant est accepté. Tous les champs renseignés sont évalués avec une sémantique AND : le JWT doit satisfaire chaque critère de correspondance renseigné. Au moins l'un de subject_prefix, claims ou condition doit être défini ; un bloc match qui ne contient que audience (ou aucun critère de correspondance) est rejeté. Cela protège contre les règles qui accepteraient tous les jetons d'un émetteur.

Critère de correspondance	Type	Sémantique
`subject_prefix`	string	Correspondance exacte avec la revendication `sub` du JWT. Un `` final en fait une correspondance par préfixe (la valeur `sub` doit commencer par les caractères précédant le ``). Sensible à la casse.
`audience`	string	La revendication `aud` du JWT doit contenir cette chaîne exacte. Lorsque `aud` est un tableau, tout élément correspondant exactement satisfait la vérification.
`claims`	map<string, string>	Chaque clé est un nom de revendication de premier niveau et chaque valeur est la valeur de chaîne exacte requise. Pour les revendications imbriquées, numériques, booléennes ou complexes comme les listes et les maps, utilisez plutôt `condition` avec une expression CEL.

Environnement d'évaluation CEL

L'expression condition a accès à une seule variable :

Variable	Type	Contenu
`claims`	map	L'ensemble complet des revendications du JWT décodé. Les objets imbriqués sont accessibles en tant que maps imbriquées.

Exemple :

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Les conditions CEL sont des frontières de sécurité. Une expression qui s'évalue à true pour plus d'entrées que prévu accorde un accès plus large que prévu. Préférez les critères de correspondance statiques lorsqu'ils expriment votre contrainte.

Erreurs

Erreurs d'échange de jeton

POST /v1/oauth/token renvoie les erreurs dans la forme d'erreur API standard. Le SDK encapsule les échecs d'échange dans une FederationExchangeError typée (ou équivalent selon le langage) qui expose le statut HTTP, le corps de la réponse et le request_id.

Statut	Erreur	Cause	Résolution
400	`invalid_request`	`federation_rule_id` est mal formé ou un champ de requête requis est manquant.	Vérifiez l'ID `fdrl_` et que le corps de la requête inclut tous les champs requis.
400	`invalid_request`	`workspace_id_required` : la règle de fédération est activée pour plus d'un espace de travail et la requête omet `workspace_id`.	Définissez `ANTHROPIC_WORKSPACE_ID` (ou le champ de corps `workspace_id` sur une requête brute) sur l'ID `wrkspc_...` auquel vous souhaitez restreindre le jeton. Voir Requête d'échange de jeton.
400

Tous les échecs invalid_grant renvoient HTTP 400 ; la cause spécifique est journalisée côté serveur uniquement et n'est pas exposée dans la réponse.

Échecs courants côté SDK

Symptôme	Cause	Résolution
Le SDK signale « no credentials » au lieu d'effectuer l'échange	L'une de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` ou `ANTHROPIC_IDENTITY_TOKEN[_FILE]` n'est pas définie et aucun profil n'est actif.	Définissez les quatre variables, ou configurez un profil.
Le SDK s'authentifie avec une clé API au lieu de fédérer	`ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` est définie et l'emporte en priorité.	Supprimez la variable de clé ou de jeton.
`FileNotFoundError` à la première requête	Le chemin dans `ANTHROPIC_IDENTITY_TOKEN_FILE` n'existe pas. Le SDK ouvre le fichier de manière différée au moment de l'échange.	Confirmez que le volume de jeton projeté est monté et que le chemin correspond.
L'échange de jeton réussit mais une requête à l'API Claude renvoie 403

Dépanner un échange échoué

Une réponse 400 invalid_grant est intentionnellement opaque ; la cause spécifique est journalisée côté serveur uniquement.

Commencez par la page d'historique d'authentification dans la Claude Console. Les tentatives d'échange récentes affichent l'émetteur et la règle qui ont été évalués, les revendications du JWT qui ont été inspectées et l'étape de validation qui a échoué, ce qui court-circuite généralement les vérifications suivantes.

Si vous devez tout de même déboguer à partir du JWT lui-même, effectuez ces vérifications dans l'ordre :

Modes de source JWKS

Lorsque vous enregistrez un émetteur de fédération, le champ jwks contrôle la manière dont Anthropic obtient les clés publiques utilisées pour vérifier les signatures JWT de cet émetteur. Il s'agit d'une union discriminée dont la clé est type :

`jwks.type`	Forme de `jwks`	Comportement	À utiliser lorsque
`discovery` (par défaut)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` est facultatif ; définissez-le lorsque l'URL de découverte diffère de `issuer_url`)	Anthropic récupère `<discovery_base or issuer_url>/.well-known/openid-configuration`, lit `jwks_uri` dans le document de découverte et récupère le JWKS à partir de là.	Votre IdP sert un document de découverte OIDC standard sur l'internet public. La plupart des fournisseurs gérés (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) le prennent en charge.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic récupère le JWKS directement depuis . L' est utilisée uniquement pour la comparaison de chaîne avec la revendication du JWT et n'est jamais contactée.

L'union discriminée rend les champs associés mutuellement exclusifs par construction. discovery et explicit_url acceptent également tous deux une chaîne ca_cert_pem facultative pour les émetteurs qui servent TLS depuis une autorité de certification privée.

Rotation des clés et mise en cache

Dans les modes discovery et explicit_url, Anthropic met en cache le JWKS récupéré. Si votre fournisseur d'identité publie une nouvelle clé de signature et commence immédiatement à signer des jetons avec celle-ci, les échanges qui présentent ces jetons peuvent échouer avec une erreur de signature pendant jusqu'à une minute le temps que le cache s'actualise.

Pour éviter cette fenêtre, publiez une nouvelle clé de signature dans le JWKS au moins 15 minutes avant que votre fournisseur d'identité ne commence à signer des jetons avec celle-ci, et conservez la clé remplacée dans le JWKS jusqu'à ce que les jetons qu'elle a signés aient expiré. Les fournisseurs d'identité gérés suivent généralement cette discipline d'eux-mêmes. Si vous exploitez votre propre émetteur (un cluster Kubernetes autogéré, un fournisseur de découverte OIDC SPIRE, ou un serveur d'autorisation personnalisé Okta avec une cadence de rotation configurée), confirmez que votre politique de rotation publie les nouvelles clés avant leur première utilisation.

En mode inline, il n'y a pas d'actualisation automatique des clés. Lorsque votre fournisseur d'identité renouvelle ses clés de signature, vous devez mettre à jour la configuration de l'émetteur avec le nouveau JWKS, sinon tous les échanges de jetons échoueront à la vérification de signature.

ANTHROPIC_SERVICE_ACCOUNT_ID

ANTHROPIC_IDENTITY_TOKEN[_FILE]

Décodez le JWT
Décodez l'assertion que vous avez envoyée afin de pouvoir comparer chaque revendication à la configuration de votre émetteur et de votre règle :
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
Vérifiez que iss correspond à l'émetteur
La revendication iss décodée doit être égale à l'issuer_url enregistrée octet par octet, y compris le schéma, le port et toute barre oblique finale. Une différence d'un seul caractère fait échouer la vérification.
Vérifiez que aud correspond à la règle
La revendication aud décodée doit contenir la valeur audience de la règle en tant que correspondance exacte. Lorsque aud est un tableau, un élément doit correspondre exactement.
Vérifiez sub et chaque entrée de claims
Comparez sub au subject_prefix de la règle (sensible à la casse ; un * final est une correspondance par préfixe, tout le reste est une correspondance exacte). Comparez chaque clé de la map claims de la règle à la revendication de premier niveau du même nom.
Vérifiez exp, nbf et iat
exp doit être dans le futur et nbf/iat doivent être dans le passé, dans la fenêtre de tolérance de 30 secondes. Si l'horloge de l'hôte de la charge de travail a dérivé, un jeton par ailleurs valide est rejeté.
Vérifiez l'accessibilité du JWKS
Pour le mode discovery, récupérez <jwks.discovery_base or issuer_url>/.well-known/openid-configuration via HTTPS public sur le port 443 et confirmez que jwks_uri se résout. Pour explicit_url, récupérez directement l'URL du JWKS. Pour inline, confirmez que la clé de signature de l'émetteur n'a pas été renouvelée depuis que vous avez enregistré les clés.
Si l'émetteur a renouvelé sa clé de signature et a immédiatement commencé à signer avec celle-ci, les échanges peuvent échouer pendant jusqu'à une minute le temps que le cache JWKS d'Anthropic s'actualise. Voir Rotation des clés et mise en cache.

url

issuer_url

iss