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 les procédures de configuration pas à pas, consultez les guides des fournisseurs.

Requête d'échange de token

POST /v1/oauth/token accepte un corps JSON utilisant l'octroi jwt-bearer de la RFC 7523. Le SDK construit 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 token

POST /v1/oauth/token renvoie une réponse de token 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.

Dans la CLI ant, les paramètres de Claude Models on Google Cloud (Anthropic managed) sont classés après les variables d'environnement de fédération et avant le profil actif. Ces paramètres sont le projet, l'ID de l'espace de travail et l'emplacement. Vous les définissez avec les options --google-cloud-* ou les variables ANTHROPIC_GOOGLE_CLOUD_*. La CLI utilise ces paramètres dès que l'un d'entre eux est défini. Avec ces paramètres, la CLI obtient ses identifiants à partir des Google Application Default Credentials.

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 <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 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

{
  "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.

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.

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, la référence de l'API Federation issuers et la référence de l'API Federation rules.

Champs des ressources

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

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 le format d'erreur de l'API standard. Le SDK signale un échec d'échange sous la forme WorkloadIdentityError, 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.

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 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

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.

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, 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 :

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

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

5. 5

   Vérifier exp, nbf et iat

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

6. 6

   Vérifier l'accessibilité du JWKS

   En mode discovery, récupérez <jwks.discovery_base or issuer_url>/.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.

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 :

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.