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 des fournisseurs.

Requête d'échange de jeton

POST /v1/oauth/token accepte un corps JSON utilisant le grant 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.

Réponse d'échange de jeton

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

Variables d'environnement

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

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.

Priorité des identifiants

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

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 ne remplit workspace_id que 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 <config_dir>/active_config (un fichier d'une ligne écrit par ant profile activate <name>)
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

Le fichier de configuration et le fichier d'identifiants comportent 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 lorsque vous rédigez une configuration à la main et le SDK traitera le fichier comme étant à la version actuelle.

Exemple de profil de fédération

{
  "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 replie 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 la Claude API le jeton d'accès émis peut appeler.

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 contre écriture) ne sont pas disponibles actuellement.

Limites des permissions

La valeur oauth_scope d'une règle de fédération est un plafond : le jeton émis ne peut jamais la dépasser. Le organization_role du compte de service cible (developer ou admin) détermine quelles portées peuvent être accordées, de sorte qu'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.

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 le détail complet des paramètres et les schémas de réponse, consultez la référence de l'API Service accounts, la référence de l'API Federation issuers et la référence de l'API Federation rules.

Champs de ressource

Champs d'URL

Les champs issuer_url, jwks.discovery_base et jwks.url sont validé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).

Vérification du JWT

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 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 du tout) est rejeté. Cela protège contre les règles qui accepteraient tous les jetons d'un émetteur.

Environnement d'évaluation CEL

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

Exemple :

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

Erreurs

Erreurs d'échange de jeton

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

Chaque refus d'assertion renvoie la même authentication_error 401 opaque 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 sur l'entrée de la tentative dans l'historique d'authentification, 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 d'historique ; leurs messages de réponse nomment directement le problème. Une 401 sans entrée d'historique correspondante signifie généralement que le federation_rule_id lui-même n'a pas été reconnu.

Échecs courants côté SDK

Dépanner un échange en échec

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, et non dans la réponse.

Un échec opaque courant est une assertion rejouée : une assertion comportant une revendication jti ne peut être échangée qu'une seule fois, de sorte qu'une charge de travail qui renvoie le même JWT (une boucle de nouvelles tentatives, ou un renouvellement qui relit un jeton non renouvelé) est rejetée au second échange. La page de l'historique d'authentification affiche ces tentatives avec la raison 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 :

1. 1

   Décoder 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"

2. 2

   Vérifier 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.

3. 3

   Vérifier que aud correspond à la règle

   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.

4. 4

   Vérifier 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 exact). Comparez chaque clé de la map claims de la règle à la revendication de niveau supérieur du même nom.

5. 5

   Vérifier exp, nbf et iat

   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 jeton par ailleurs valide est rejeté.

6. 6

   Vérifier 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 pendant que le cache JWKS d'Anthropic se rafraîchit. Consultez Rotation des clés et mise en cache.

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 indexée sur type :

L'union discriminée rend les champs associés mutuellement exclusifs par construction. discovery et explicit_url acceptent également tous deux une chaîne facultative ca_cert_pem 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 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 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.