--- title: Référence WIF url: https://platform.claude.com/docs/fr/manage-claude/wif-reference description: Variables d'environnement, règles de validation, configuration de profil et référence des erreurs pour Workload Identity Federation. --- Cette page rassemble les surfaces de configuration, les contraintes de validation et les correspondances d'erreurs pour [Workload Identity Federation](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation). Pour les guides de configuration pas à pas, consultez les [guides des fournisseurs](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation#identity-providers). ## Requête d'échange de token `POST /v1/oauth/token` accepte un corps JSON utilisant le grant `jwt-bearer` de la [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). Le SDK construit cette requête pour vous à partir des [variables d'environnement](https://platform.claude.com/docs/fr/manage-claude/wif-reference#environment-variables) ; les exemples cURL de chaque guide de fournisseur montrent le corps brut. | Champ | Obligatoire | 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 balisé (`fdrl_...`) de la règle de fédération à évaluer. | | `organization_id` | Oui | UUID de votre organisation Anthropic. | | `service_account_id` | Oui | ID balisé (`svac_...`) du compte de service cible. | | `workspace_id` | Conditionnel | ID balisé (`wrkspc_...`) de l'espace de travail auquel limiter la portée du jeton émis. Obligatoire lorsque la règle est activée pour plus d'un espace de travail. Lorsqu'il est omis, le serveur sélectionne l'unique espace de travail activé de la règle. La valeur littérale `default` fonctionne également pour le Default Workspace de l'organisation, mais elle est dépréciée ; utilisez l'ID `wrkspc_...` de cet espace de travail. | ## Réponse d'échange de token `POST /v1/oauth/token` renvoie une réponse de token OAuth 2.0 standard ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-5.1)) : | Champ | Type | Description | | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | `access_token` | string | Le token Anthropic de courte durée, préfixé `sk-ant-oat01-...`. Transmettez-le sous la forme `Authorization: Bearer `. | | `token_type` | string | Toujours `Bearer`. | | `expires_in` | integer | Secondes avant l'expiration du token. | | `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 token fédéré sans argument de constructeur. | Variable | Obligatoire | Description | Exemple | | ------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `ANTHROPIC_FEDERATION_RULE_ID` | Oui | ID balisé de la règle de fédération à évaluer. | `fdrl_...` | | `ANTHROPIC_ORGANIZATION_ID` | Oui | UUID de votre organisation Anthropic. Vous le trouverez sur la page [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) de la Claude Console. | `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 font l'objet d'une rotation sur le disque soient toujours à jour. | `/var/run/secrets/anthropic.com/token` | | `ANTHROPIC_IDENTITY_TOKEN` | L'une de `_TOKEN_FILE` ou `_TOKEN` | Le JWT littéral sous forme de chaîne. À utiliser lorsque votre plateforme injecte le jeton sous forme de variable d'environnement plutôt que de fichier. | `eyJhbGciOiJSUzI1NiIs...` | | `ANTHROPIC_SERVICE_ACCOUNT_ID` | Oui | ID balisé du compte de service Anthropic cible au nom duquel agit le jeton d'accès émis. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Conditionnel | ID balisé de l'espace de travail auquel limiter la portée du jeton émis. Obligatoire lorsque la règle de fédération est activée pour plus d'un espace de travail ; facultatif lorsque la règle est liée à un seul espace de travail. La portée du jeton émis est limitée à cet espace de travail au moment de l'échange, donc changer d'espace de travail nécessite un nouvel échange. La valeur littérale `default` fonctionne également pour le Default Workspace, mais elle est dépréciée ; utilisez son ID `wrkspc_...`. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | Non | Nom d'un [profil de configuration](https://platform.claude.com/docs/fr/manage-claude/wif-reference#profile-configuration-file) à charger. Prévaut sur les variables d'environnement de fédération de ce tableau. | `staging-profile` | Le chemin de fédération direct par variable d'environnement s'active uniquement lorsque `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, et l'un de `ANTHROPIC_IDENTITY_TOKEN_FILE` ou `ANTHROPIC_IDENTITY_TOKEN` sont tous définis. `ANTHROPIC_WORKSPACE_ID` est lu en parallèle mais ne conditionne pas l'activation. Une variable définie sur une chaîne vide occupe toujours son emplacement dans la chaîne de priorité des identifiants. Si `ANTHROPIC_API_KEY=""` est exporté, le SDK sélectionne le chemin de clé API avec une clé vide plutôt que de passer à la fédération. Désactivez 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 de constructeur (`api_key=`, `auth_token=`, `credentials=`) | Remplace toujours tout le reste. | | 2 | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` | Masque entièrement la fédération. Désactivez-les lors de la migration depuis les clés API. | | 3 | `ANTHROPIC_PROFILE` | Charge `/configs/.json`. Un profil nommé manquant est une erreur, pas un passage au suivant. | | 4 | Variables d'environnement de fédération | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`. | | 5 | Profil actif | Résolu à partir de `/active_config`, avec repli sur un profil nommé `default`. | 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 de livrer des 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 : 1. `$ANTHROPIC_CONFIG_DIR` 2. `~/.config/anthropic` sur Linux et macOS 3. `%APPDATA%\Anthropic` sur Windows ### Profil actif Le nom du profil actif se résout dans cet ordre : 1. `$ANTHROPIC_PROFILE` 2. Le contenu de `/active_config` (un fichier d'une ligne écrit par `ant profile activate `) 3. Le nom littéral `default` Claude Code et le Claude Agent SDK respectent ce même ordre de résolution, donc un profil de fédération configuré ici authentifie également ces outils sans configuration supplémentaire. ### Disposition des fichiers | Chemin | Contenu | Sensibilité | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | `/configs/.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é. | | `/credentials/.json` | `version`, le `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 portent tous deux un champ `version` de type chaîne au niveau supérieur 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 lors de la rédaction manuelle d'une configuration et le SDK traite le fichier comme la version actuelle. ### Exemple de profil de fédération ```json 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` de l'environnement. ## Portées OAuth Le `oauth_scope` que vous définissez sur une règle de fédération détermine quels endpoints de l'API Claude le token d'accès généré peut appeler. | Portée | Accorde l'accès à | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `workspace:developer` | Tous les endpoints non administratifs de l'API Claude dans l'espace de travail de la règle : [Messages](https://platform.claude.com/docs/fr/api/messages) (y compris le streaming et le comptage de tokens), [Models](https://platform.claude.com/docs/fr/api/models/list), [Managed Agents](https://platform.claude.com/docs/fr/managed-agents/overview) et leurs sessions, [Files](https://platform.claude.com/docs/fr/build-with-claude/files), et [Skills](https://platform.claude.com/docs/fr/build-with-claude/skills-guide). Cela correspond à l'accès dont dispose une clé API d'espace de travail dans le même espace de travail. | | `workspace:inference` | Les endpoints d'inférence dans l'espace de travail de la règle : [Messages](https://platform.claude.com/docs/fr/api/messages) (y compris le streaming et le comptage de tokens), [Models](https://platform.claude.com/docs/fr/api/models/list), et l'[endpoint de chat compatible OpenAI](https://platform.claude.com/docs/fr/cli-sdks-libraries/libraries/openai-sdk). À utiliser pour les charges de travail qui ont uniquement besoin d'appeler Claude et n'ont jamais besoin de gérer les Files, Skills ou autres ressources. | | `workspace:manage_tunnels` | L'[API des tunnels MCP](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/reference#tunnels-api) : créer, lister et obtenir des tunnels, enregistrer et archiver des certificats CA, révéler et faire tourner le token 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 à partir d'elle. | | `org:admin` | Accès complet à l'[Admin API](https://platform.claude.com/docs/fr/manage-claude/admin-api) (membres de l'organisation, invitations, espaces de travail, clés API, et le reste). Un token OAuth `org:admin` ne peut créer ou modifier que des règles limitées à `workspace:developer` ou `workspace:inference`, et ne peut pas mettre à jour un émetteur qui sous-tend une règle avec toute autre portée ; consultez les [contraintes](https://platform.claude.com/docs/fr/manage-claude/wif-admin-api#permissions-and-constraints). | Une requête vers un endpoint en dehors de la portée du token renvoie HTTP 403. Des portées plus fines (par ressource, ou lecture versus écriture) ne sont pas disponibles actuellement. ### Limites de permissions Le `oauth_scope` d'une règle de fédération est un plafond : le token généré ne peut jamais le dépasser. Le `organization_role` (`developer` ou `admin`) du compte de service cible détermine quelles portées peuvent être accordées, donc une règle qui accorde `org:admin` doit cibler un compte de service avec `organization_role=admin`. Les permissions effectives sont l'intersection de la portée de la règle et du rôle du compte de service. | `oauth_scope` de la règle | `organization_role` du compte de service | Permissions effectives | | ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Accès à l'API Claude uniquement dans l'espace de travail de la règle. La portée plafonne le token en dessous du rôle. | | `org:admin` | `admin` | Accès complet à l'Admin API (membres de l'organisation, invitations, espaces de travail, clés API, et le reste), moins les exclusions de l'appelant OAuth ; consultez les [contraintes](https://platform.claude.com/docs/fr/manage-claude/wif-admin-api#permissions-and-constraints). | ## 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. Pour les détails complets des paramètres et les schémas de réponse, consultez la [référence de l'API Service accounts](https://platform.claude.com/docs/fr/api/organization/service_accounts), la [référence de l'API Federation issuers](https://platform.claude.com/docs/fr/api/organization/federation/issuers) et la [référence de l'API Federation rules](https://platform.claude.com/docs/fr/api/organization/federation/rules). ### 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` | Requis à la création sauf si `applies_to_all_workspaces` est vrai. L'espace de travail (`wrkspc_...`) dont le quota, la facturation et les limites de débit s'appliquent aux tokens générés sous cette règle. Doit être un espace de travail dans la même organisation, et le compte de service cible doit être membre de cet espace de travail. | | `applies_to_all_workspaces` | Booléen. Définissez `true` pour activer la règle dans chaque espace de travail de l'organisation au lieu d'en nommer un ; soit ceci, soit `workspace_id` est requis à la création. | | `token_lifetime_seconds` | Entier entre `60` et `86400` (1 minute à 24 heures). Par défaut `3600`. Les valeurs en dehors de cette plage sont rejetées au moment de la requête. Consultez [Durée de vie et renouvellement des tokens](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation#token-lifetime-and-refresh). | ### 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 en mode `discovery` lorsque `jwks.discovery_base` est défini, le `issuer_url` est comparé à la revendication `iss` du JWT en tant que chaîne et n'est jamais récupéré, il 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` correspondant à une clé du JWKS de l'émetteur. Les jetons sans `kid` sont rejetés. | | Revendications obligatoires | `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. | | Usage unique | Une assertion qui comporte une revendication `jti` ne peut être échangée qu'une seule fois par émetteur : un échange répété avec le même `jti` est rejeté comme une rediffusion. Le champ `check_jti` de l'émetteur (activé par défaut) contrôle cette vérification ; les assertions sans revendication `jti` n'y sont pas soumises. Consultez la [référence de l'API Federation issuers](https://platform.claude.com/docs/fr/api/organization/federation/issuers). | | Durée de vie maximale | La durée de vie du jeton (`exp` moins `iat`) ne doit pas dépasser le maximum configuré pour l'émetteur (1 heure par défaut, configurable pour chaque émetteur dans la Claude Console). | | Décalage d'horloge | Une tolérance de 30 secondes est appliquée à `exp`, `nbf` et `iat`. | ## 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 ET : le JWT doit satisfaire chaque matcher 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 matcher du tout) est rejeté. Cela protège contre les règles qui accepteraient chaque token d'un émetteur. | Matcher | Type | Sémantique | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `subject_prefix` | string | Correspondance exacte avec la revendication `sub` du JWT. Un `*` final en fait une correspondance de préfixe (la valeur `sub` doit commencer par les caractères avant 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\ | Chaque clé est un nom de revendication de niveau supérieur 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. | | `condition` | string (CEL) | Une expression [CEL](https://cel.dev/) qui doit s'évaluer à `true`. | ### Environnement d'évaluation CEL L'expression `condition` a accès à une seule variable : | Variable | Type | Contenu | | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | | `claims` | map | L'ensemble complet des revendications décodées du JWT. Les objets imbriqués sont accessibles en tant que maps imbriquées. | Exemple : ```text wrap claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"] ``` Les conditions CEL sont des limites 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 matchers statiques lorsqu'ils expriment votre contrainte. ## Erreurs ### Erreurs d'échange de token `POST /v1/oauth/token` renvoie les erreurs selon la [forme d'erreur de l'API](https://platform.claude.com/docs/fr/api/errors) standard. Le SDK signale un échec d'échange sous la forme `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), qui fournit le statut HTTP et les détails de l'erreur issus du corps de la réponse. L'ID de requête figure sur l'erreur en Python, TypeScript et Ruby, et dans les en-têtes de réponse de l'exception en Java. En Go, il figure uniquement dans le message de l'erreur, car le type de l'erreur se trouve dans un package interne ; les erreurs C# et PHP ne le contiennent pas. | Statut | Erreur | Cause | Résolution | | ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `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_error` | `workspace_id` est présent mais n'est pas un ID `wrkspc_...` bien formé ou le littéral `default`. | Corrigez la valeur `workspace_id` ; le message de réponse nomme le format attendu. | | 401 | `authentication_error` | La revendication `iss` du JWT n'est pas exactement égale au `issuer_url` enregistré. | Comparez octet par octet, y compris les barres obliques finales et le schéma : `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | La récupération du JWKS a échoué, le JWKS est obsolète, ou le JWT a été signé avec une clé absente du JWKS. | Pour le mode `inline`, mettez à jour l'émetteur avec les clés renouvelées. Pour `discovery` et `explicit_url`, confirmez que l'endpoint JWKS est accessible sur le port 443 ; si l'émetteur a récemment fait tourner sa clé de signature, consultez [Rotation et mise en cache des clés](https://platform.claude.com/docs/fr/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | La revendication `exp` du JWT est dans le passé (au-delà de la fenêtre de décalage de 30 secondes). | Confirmez que votre fournisseur d'identité projette un token frais et que le SDK relit le fichier de token. | | 401 | `authentication_error` | Le JWT a été vérifié mais ses revendications ne satisfont pas le bloc `match` de la règle. | Décodez le JWT et comparez chaque revendication à la règle. `subject_prefix` est sensible à la casse. `audience` nécessite une correspondance exacte d'élément. | | 401 | `authentication_error` | Le `federation_rule_id` n'existe pas, est archivé, ou le JWT n'y est pas autorisé (consolidé pour empêcher l'énumération). | Confirmez l'ID de la règle dans la Claude Console et que la règle n'a pas été archivée. | | 401 | `authentication_error` | La règle de fédération est activée pour plus d'un espace de travail et la requête omet `workspace_id`. L'entrée de l'historique d'authentification affiche la raison `workspace_id_required`. | Définissez `ANTHROPIC_WORKSPACE_ID` (ou le champ de corps `workspace_id` sur une requête brute) sur l'ID `wrkspc_...` auquel vous voulez limiter la portée du token. Consultez [Requête d'échange de token](https://platform.claude.com/docs/fr/manage-claude/wif-reference#token-exchange-request). | Chaque refus d'assertion renvoie la même erreur opaque `401` `authentication_error` avec le message fixe `Authentication failed`, quelle que soit la vérification ayant échoué ; une erreur distinguable permettrait à un appelant de sonder la configuration des règles. La raison du refus est enregistrée dans l'entrée de la tentative dans l'[historique d'authentification](https://platform.claude.com/settings/workload-identity-federation?tab=history) de la Claude Console, par exemple `match_subject_prefix` lorsque la revendication `sub` ne satisfait pas le `subject_prefix` de la règle, ou `workspace_id_required` lorsque la règle couvre plusieurs espaces de travail et que la requête n'en nomme aucun. Les requêtes rejetées avant que l'organisation de la règle ne soit corroborée (la famille `400 invalid_request_error` ci-dessus) ne laissent aucune entrée dans l'historique ; leurs messages de réponse indiquent directement le problème. Une erreur `401` sans entrée correspondante dans l'historique signifie généralement que le `federation_rule_id` lui-même n'a pas été reconnu. ### Échecs courants côté SDK | Symptôme | Cause | Résolution | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Le SDK signale « no credentials » au lieu d'échanger | L'un de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID`, ou `ANTHROPIC_IDENTITY_TOKEN[_FILE]` n'est pas défini 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éfini et l'emporte en priorité. | Désactivez la variable de clé ou de token. | | `FileNotFoundError` à la première requête | Le chemin dans `ANTHROPIC_IDENTITY_TOKEN_FILE` n'existe pas. Le SDK ouvre le fichier de manière paresseuse au moment de l'échange. | Confirmez que le volume de token projeté est monté et que le chemin correspond. | | L'échange de token réussit mais une requête à l'API Claude renvoie 403 | La portée du token généré n'accorde pas l'accès à cet endpoint. | Vérifiez le `oauth_scope` de la règle par rapport aux [Portées OAuth](https://platform.claude.com/docs/fr/manage-claude/wif-reference#oauth-scopes). | | L'authentification échoue avec un identifiant vide | Une variable d'environnement d'identifiant est exportée mais définie sur une chaîne vide. Les valeurs vides l'emportent toujours dans leur emplacement de priorité. | Désactivez la variable avec `unset VAR` plutôt que `VAR=""`. | ## Dépanner un échange échoué Une réponse `401` `authentication_error` est intentionnellement opaque et son message est toujours `Authentication failed` ; la raison du refus est enregistrée dans l'historique d'authentification, pas dans la réponse. Commencez par la [page d'historique d'authentification](https://platform.claude.com/settings/workload-identity-federation?tab=history) dans la Claude Console. Les tentatives d'échange récentes font apparaître l'émetteur et la règle qui ont été évalués, les revendications du JWT qui ont été inspectées, et quelle étape de validation a échoué, ce qui court-circuite généralement les vérifications suivantes. Un échec opaque courant est une assertion rediffusée : une assertion qui porte une revendication `jti` ne peut être [échangée qu'une seule fois](https://platform.claude.com/docs/fr/manage-claude/wif-reference#jwt-verification), donc une charge de travail qui renvoie le même JWT (une boucle de nouvelle tentative, ou un renouvellement qui relit un token non renouvelé) est rejetée au deuxième échange. La page d'historique d'authentification affiche ces tentatives avec la raison `jti_reused` ; la solution est de générer une assertion fraîche pour chaque échange. Si vous avez encore besoin de déboguer à partir du JWT lui-même, parcourez ces vérifications dans l'ordre : Décodez l'assertion que vous avez envoyée afin de pouvoir comparer chaque revendication à votre configuration d'émetteur et de règle : ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` La revendication `iss` décodée doit être égale au `issuer_url` enregistré octet par octet, y compris le schéma, le port, et toute barre oblique finale. Une non-correspondance sur un seul caractère fait échouer la vérification. La revendication `aud` décodée doit contenir la valeur `audience` de la règle en correspondance exacte. Lorsque `aud` est un tableau, un élément doit correspondre exactement. Comparez `sub` au `subject_prefix` de la règle (sensible à la casse ; un `*` final est une correspondance de préfixe, tout le reste est exact). Comparez chaque clé de la map `claims` de la règle à la revendication de niveau supérieur du même nom. `exp` doit être dans le futur et `nbf`/`iat` doivent être dans le passé, dans la fenêtre de décalage de 30 secondes. Si l'horloge de l'hôte de la charge de travail a dérivé, un token par ailleurs valide est rejeté. Pour le mode `discovery`, récupérez `/.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 JWKS. Pour `inline`, confirmez que la clé de signature de l'émetteur n'a pas tourné depuis que vous avez enregistré les clés. Si l'émetteur a fait tourner sa clé de signature et a immédiatement commencé à signer avec elle, les échanges peuvent échouer pendant jusqu'à une minute pendant que le cache JWKS d'Anthropic se rafraîchit. Consultez [Rotation et mise en cache des clés](https://platform.claude.com/docs/fr/manage-claude/wif-reference#key-rotation-and-caching). ## Modes de source JWKS Lorsque vous enregistrez un émetteur de fédération, le champ `jwks` contrôle comment Anthropic obtient les clés publiques utilisées pour vérifier les signatures JWT de cet émetteur. C'est une union discriminée indexée sur `type` : | `jwks.type` | Forme de `jwks` | Comportement | À utiliser quand | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 `/.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 `url`. Le `issuer_url` est utilisé uniquement pour la comparaison de chaîne avec la revendication `iss` du JWT et n'est jamais contacté. | Votre IdP ne sert pas de document de découverte, ou la découverte est interne uniquement mais le JWKS est accessible publiquement. | | `inline` | `{ "type": "inline", "keys": [...] }` | Vous fournissez le tableau d'objets JWK en ligne (le tableau `keys` du document JWKS, pas l'objet wrapper). Anthropic ne fait aucune requête sortante. Le `issuer_url` est utilisé uniquement pour la comparaison `iss`. | Environnements isolés (air-gapped), clusters Kubernetes autogérés avec des URL d'émetteur internes au cluster, ou lorsque vous voulez un contrôle explicite sur la rotation des clés. | L'union discriminée rend les champs compagnons mutuellement exclusifs par construction. `discovery` et `explicit_url` acceptent également une chaîne `ca_cert_pem` facultative pour les émetteurs qui servent TLS à partir d'une CA privée. ### Rotation et mise en cache des clés 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 tokens avec elle, les échanges qui présentent ces tokens peuvent échouer avec une erreur de signature pendant jusqu'à 1 minute pendant que le cache se rafraîchit. 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 tokens avec elle, et conservez la clé remplacée dans le JWKS jusqu'à ce que les tokens 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 de rafraîchissement automatique des clés. Lorsque votre fournisseur d'identité fait tourner ses clés de signature, vous devez mettre à jour la configuration de l'émetteur avec le nouveau JWKS sinon tous les échanges de tokens échoueront à la vérification de signature.