--- 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 des profils 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 procédures 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 l'octroi `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 | 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 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 le token émis. 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. 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 jeton Anthropic de courte durée, préfixé par `sk-ant-oat01-...`. Transmettez-le sous la forme `Authorization: Bearer `. | | `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 aucun argument de constructeur. | Variable | Requis | 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`) dans 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 en tant que variable d'environnement plutôt que sous forme 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 le jeton émis. Requis 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. Le jeton émis est limité à 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 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 peut tout de même occuper sa place dans la chaîne de priorité des identifiants. 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 ces variables lors de la migration depuis des clés API. | | 3 | `ANTHROPIC_PROFILE` | Charge `/configs/.json`. Un profil nommé manquant constitue une erreur, et non un passage à la source suivante. | | 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 complètent les champs que le profil omet, mais ne remplacent jamais les champs que le profil définit explicitement. Par exemple, `ANTHROPIC_WORKSPACE_ID` renseigne `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 les paramètres de fédération avec votre image de conteneur ou de basculer entre 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` sous Linux et macOS 3. `%APPDATA%\Anthropic` sous Windows ### Profil actif Le nom du profil actif est résolu 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, de sorte qu'un profil de fédération configuré ici authentifie également ces outils sans configuration supplémentaire. ### Organisation 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é à une image sans risque. | | `/credentials/.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 anciens formats ; omettez-le lorsque vous rédigez une configuration à la main, et le SDK traitera le fichier comme étant de 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` depuis l'environnement. ## Portées OAuth L'`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](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 points de terminaison 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 le [point de terminaison de chat compatible OpenAI](https://platform.claude.com/docs/fr/cli-sdks-libraries/libraries/openai-sdk). Utilisez-la pour les charges de travail qui ont uniquement besoin d'appeler Claude et n'ont jamais besoin de gérer des Files, des Skills ou d'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 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 à partir de celle-ci. | | `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, etc.). Un jeton 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 ayant une 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 point de terminaison situé en dehors de la portée du jeton renvoie HTTP 403. Des portées plus fines (par ressource, ou lecture par opposition à écriture) ne sont pas disponibles actuellement. ### Limites des autorisations L'`oauth_scope` d'une règle de fédération est un plafond : le jeton émis ne peut jamais le dépasser. L'`organization_role` du compte de service cible (`developer` ou `admin`) détermine quelles portées peuvent être accordées ; ainsi, une règle qui accorde `org:admin` doit cibler un compte de service avec `organization_role=admin`. Les autorisations effectives correspondent à 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 | Autorisations effectives | | ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `workspace:developer` | `admin` | Accès à l'API Claude dans l'espace de travail de la règle uniquement. La portée plafonne le jeton 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, etc.), moins les exclusions applicables aux appelants 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, ainsi que 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 des ressources | 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` vaut true. L'espace de travail (`wrkspc_...`) dont le quota, la facturation et les limites de débit s'appliquent aux jetons émis dans le cadre de 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. | | `applies_to_all_workspaces` | Booléen. Définissez-le sur `true` pour activer la règle dans tous les espaces de travail de l'organisation au lieu d'en nommer un ; ce champ ou `workspace_id` est requis à la création. | | `token_lifetime_seconds` | Entier compris entre `60` et `86400` (1 minute à 24 heures). Valeur 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 actualisation des jetons](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 adresses IP littérales ne sont pas acceptées. | 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`, ainsi qu'en 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` correspondant à une clé du JWKS de l'émetteur. Les jetons sans `kid` sont rejetés. | | Revendications requises | `sub` doit être présente. `iat` doit être présente et ne pas se situer dans le futur. `exp` doit être présente et se situer dans le futur. | | Usage unique | Une assertion qui comporte une revendication `jti` ne peut être échangée qu'une seule fois par émetteur : la répétition d'un échange avec le même `jti` est rejetée comme une relecture. 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 critère de correspondance renseigné. Au moins l'un des champs `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 de 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 exactement cette chaîne. Lorsque `aud` est un tableau, tout élément correspondant exactement satisfait la vérification. | | `claims` | map\ | 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. | | `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 sous forme de maps imbriquées. | Exemple : ```text wrap claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"] ``` Les conditions CEL constituent 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. Privilégiez les critères de correspondance statiques lorsqu'ils permettent d'exprimer votre contrainte. ## Erreurs ### Erreurs d'échange de jeton `POST /v1/oauth/token` renvoie les erreurs dans le [format 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 requis de la requête 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 ni un ID `wrkspc_...` bien formé ni la valeur littérale `default`. | Corrigez la valeur de `workspace_id` ; le message de réponse indique le format attendu. | | 401 | `authentication_error` | La revendication `iss` du JWT n'est pas exactement égale à l'`issuer_url` enregistrée. | 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. | En mode `inline`, mettez à jour l'émetteur avec les clés renouvelées. Pour `discovery` et `explicit_url`, vérifiez que le point de terminaison JWKS est accessible sur le port 443 ; si l'émetteur a récemment renouvelé sa clé de signature, consultez [Rotation des clés et mise en cache](https://platform.claude.com/docs/fr/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | La revendication `exp` du JWT se situe dans le passé (au-delà de la fenêtre de décalage de 30 secondes). | Vérifiez que votre fournisseur d'identité projette un jeton récent et que le SDK relit le fichier de jeton. | | 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` exige une correspondance exacte d'un élément. | | 401 | `authentication_error` | Le `federation_rule_id` n'existe pas, est archivé, ou le JWT n'est pas autorisé pour celui-ci (regroupé pour empêcher l'énumération). | Vérifiez 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 indique le motif `workspace_id_required`. | Définissez `ANTHROPIC_WORKSPACE_ID` (ou le champ de corps `workspace_id` dans une requête brute) sur l'ID `wrkspc_...` auquel vous souhaitez limiter le jeton. 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. Le motif du refus est enregistré 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'effectuer l'échange | L'une des variables `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 d'utiliser la fédération | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` est définie et l'emporte en priorité. | Supprimez la variable de clé ou de jeton. | | `FileNotFoundError` lors de la première requête | Le chemin indiqué dans `ANTHROPIC_IDENTITY_TOKEN_FILE` n'existe pas. Le SDK ouvre le fichier de manière différée, au moment de l'échange. | Vérifiez que le volume du jeton projeté est monté et que le chemin correspond. | | L'échange de jeton réussit, mais une requête à l'API Claude renvoie 403 | La portée du jeton émis ne donne pas accès à ce point de terminaison. | Comparez l'`oauth_scope` de la règle 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 peuvent tout de même remporter leur place dans l'ordre de priorité. | Supprimez la variable avec `unset VAR` plutôt qu'avec `VAR=""`. | ## Dépanner un échange ayant échoué Une réponse `401` `authentication_error` est volontairement opaque et son message est toujours `Authentication failed` ; le motif du refus est enregistré dans l'historique d'authentification, et non dans la réponse. Commencez par la [page de l'historique d'authentification](https://platform.claude.com/settings/workload-identity-federation?tab=history) dans la Claude Console. Les tentatives d'échange récentes indiquent l'émetteur et la règle évalués, les revendications du JWT inspectées et l'étape de validation ayant échoué, ce qui permet généralement de court-circuiter les vérifications suivantes. Un échec opaque courant est une assertion rejouée : une assertion qui comporte une revendication `jti` ne peut être [échangée qu'une seule fois](https://platform.claude.com/docs/fr/manage-claude/wif-reference#jwt-verification), de sorte qu'une charge de travail qui renvoie le même JWT (une boucle de nouvelles tentatives, ou une actualisation qui relit un jeton non renouvelé) est rejetée lors du second échange. La page de l'historique d'authentification affiche ces tentatives avec le motif `jti_reused` ; la solution consiste à émettre une nouvelle assertion pour chaque échange. Si vous devez encore déboguer à partir du JWT lui-même, effectuez ces vérifications dans l'ordre : 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 : ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` La revendication `iss` décodée doit être égale octet par octet à l'`issuer_url` enregistrée, 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. 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 indique une correspondance de 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 portant le même nom. `exp` doit se situer dans le futur et `nbf`/`iat` 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 jeton par ailleurs valide est rejeté. En mode `discovery`, récupérez `/.well-known/openid-configuration` via HTTPS public sur le port 443 et vérifiez que `jwks_uri` se résout. Pour `explicit_url`, récupérez directement l'URL du JWKS. Pour `inline`, vérifiez que la clé de signature de l'émetteur n'a pas été renouvelée depuis l'enregistrement des 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. Consultez [Rotation des clés et mise en cache](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 la manière dont Anthropic obtient les clés publiques utilisées pour vérifier les signatures des JWT de cet émetteur. Il s'agit d'une union discriminée indexée sur `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 `/.well-known/openid-configuration`, lit `jwks_uri` dans le document de découverte et récupère le JWKS à partir de là. | Votre IdP fournit 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`. L'`issuer_url` sert uniquement à la comparaison de chaînes avec la revendication `iss` du JWT et n'est jamais contactée. | Votre IdP ne fournit pas de document de découverte, ou la découverte est uniquement interne 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, et non l'objet englobant). Anthropic n'effectue aucune requête sortante. L'`issuer_url` sert uniquement à la comparaison avec `iss`. | Environnements isolés (air-gapped), clusters Kubernetes autogérés avec des URL d'émetteur internes au cluster, ou lorsque vous souhaitez un contrôle explicite sur la rotation des clés. | L'union discriminée rend les champs associés 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 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'à 1 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'à l'expiration des jetons qu'elle a signés. 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), vérifiez 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, faute de quoi tous les échanges de jetons échoueront à la vérification de signature.