Utiliser WIF avec SPIFFE

SPIFFE est la norme CNCF pour l'émission d'identités aux charges de travail. SPIRE est son implémentation de référence open source, et plusieurs produits commerciaux émettent également des identités conformes à SPIFFE. Anthropic fédère avec toute implémentation SPIFFE qui émet des JWT-SVID compatibles OIDC. Pour une liste à jour des implémentations, consultez Commercial software that implements SPIFFE sur le site du projet SPIFFE.

La fédération fonctionne soit via un document de découverte OIDC à une URL HTTPS publique (mode discovery, soumis aux contraintes d'URL), soit en enregistrant directement le JWKS (mode inline).

La spécification JWT-SVID définit sub comme l'identifiant SPIFFE de la charge de travail, et la Workload API de SPIFFE exige que l'appelant fournisse aud au moment de la récupération, de sorte que ces revendications sont identiques d'une implémentation à l'autre. Anthropic exige en plus iss et iat, qu'aucune des deux n'est imposée par la spécification JWT-SVID, donc configurez votre implémentation pour renseigner les deux (dans SPIRE, iss correspond au paramètre serveur jwt_issuer et iat est défini automatiquement). Une fois ces éléments en place, les sections Configurer Anthropic, Acquérir et utiliser le jeton et Délimiter votre règle de ce guide s'appliquent à toute implémentation SPIFFE.

SPIFFE attribue à chaque charge de travail un URI d'identité stable de la forme spiffe://<trust-domain>/<path>, et SPIRE émet cette identité sous forme de JWT-SVID à la demande via la Workload API. Un JWT-SVID est un JWT signé ordinaire dont la revendication sub est l'identifiant SPIFFE de la charge de travail et dont la revendication aud est fournie par la charge de travail au moment de la récupération.

Le pont entre un domaine de confiance SPIRE et l'OIDC standard est le SPIRE OIDC Discovery Provider, un assistant autonome qui publie /.well-known/openid-configuration et un point de terminaison JWKS pour les clés de signature JWT du domaine de confiance. Avec le fournisseur de découverte en cours d'exécution, un JWT-SVID se valide comme n'importe quel autre jeton OIDC : enregistrez l'URL de découverte comme émetteur de fédération, écrivez une règle de fédération qui correspond à l'identifiant SPIFFE de la charge de travail, et faites en sorte que la charge de travail présente son JWT-SVID au point de terminaison d'échange de jetons d'Anthropic.

Les exemples de cette page utilisent SPIRE et s'appliquent partout où SPIRE Agent s'exécute : pods Kubernetes, machines virtuelles et hôtes bare-metal.



Prérequis

• Une familiarité avec les concepts WIF : comptes de service, émetteurs de fédération et règles de fédération.
• Un déploiement SPIFFE avec des identités de charge de travail émises (les exemples de cette page utilisent SPIRE Server et Agent), et des entrées d'enregistrement pour les charges de travail qui doivent appeler l'API Claude.
• Un point de terminaison de découverte OIDC pour le domaine de confiance (dans SPIRE, l'OIDC Discovery Provider) s'exécutant avec un point de terminaison HTTPS accessible publiquement, ou le JWKS exporté pour un enregistrement inline.
• Votre émetteur SPIFFE configuré pour définir la revendication iss des JWT-SVID sur la valeur que vous enregistrerez comme issuer_url de l'émetteur de fédération. Pour le mode discovery, il s'agit de l'URL publique du point de terminaison de découverte (dans SPIRE, le paramètre serveur jwt_issuer).
• Des JWT-SVID disponibles pour vos charges de travail. WIF accepte uniquement les JWT-SVID, pas les X.509-SVID.
• L'autorisation de créer des comptes de service, des émetteurs de fédération et des règles de fédération dans la Claude Console pour votre organisation Anthropic.

La valeur d'audience à demander lors de la récupération d'un JWT-SVID est toujours https://api.anthropic.com. Utilisez cette valeur dans le jwt_audience de spiffe-helper, l'appel FetchJWTSVID de la Workload API et le matcher audience de la règle de fédération.



Configurer SPIRE

Les instructions de cette section sont spécifiques à SPIRE. Si vous utilisez un autre émetteur SPIFFE, configurez son point de terminaison de découverte OIDC et la récupération des JWT-SVID selon sa propre documentation, puis continuez à Configurer Anthropic.

Si vous exécutez déjà SPIRE avec l'OIDC Discovery Provider, la fédération avec Anthropic nécessite trois choses côté SPIRE : un jwt_issuer qui correspond à l'URL de découverte, une entrée d'enregistrement pour la charge de travail qui appellera l'API Claude, et un moyen pour cette charge de travail de récupérer un JWT-SVID avec l'audience Anthropic. Les sous-sections suivantes détaillent chacun de ces points. Les extraits de configuration ne montrent que les paramètres pertinents pour la fédération Anthropic, pas des configurations de déploiement SPIRE complètes.



Vérifier l'émetteur JWT

Anthropic valide un JWT-SVID en faisant correspondre sa revendication iss à un émetteur de fédération enregistré et en récupérant le JWKS à partir du document de découverte de cet émetteur. Deux paramètres SPIRE doivent s'accorder sur la même URL : le jwt_issuer de SPIRE Server (qui devient la revendication iss de chaque JWT-SVID émis) et la liste domains de l'OIDC Discovery Provider (qui détermine l'hôte à partir duquel le document de découverte et le JWKS sont servis). Cette URL partagée est celle que vous enregistrez auprès d'Anthropic.

Le domaine de confiance et l'URL de l'émetteur sont indépendants. Le domaine de confiance (spiffe://prod.example.com) délimite la revendication sub. L'URL de l'émetteur (https://oidc-discovery.prod.example.com) est l'endroit où Anthropic récupère les clés de signature. Ils n'ont pas besoin de partager un nom d'hôte.

Confirmez que jwt_issuer est défini dans la configuration de SPIRE Server et pointe vers l'URL publique du fournisseur de découverte. L'exemple suivant montre également une durée de vie par défaut des JWT-SVID. La valeur par défaut intégrée de SPIRE est de 5 minutes, ce qui est suffisamment court pour qu'une rotation continue soit nécessaire (voir Exécuter spiffe-helper). Le point de terminaison d'échange de jetons d'Anthropic rejette tout jeton d'identité dont la durée de vie dépasse le maximum configuré de l'émetteur de fédération, qui est de 1 heure par défaut (voir Règles de validation). Cette vérification s'applique à toutes les implémentations SPIFFE, pas seulement à SPIRE, donc maintenez default_jwt_svid_ttl (ou toute valeur de remplacement par entrée) à ce maximum ou en dessous.

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

Dans la configuration de l'OIDC Discovery Provider, le même nom d'hôte doit apparaître sous domains, et le fournisseur doit pouvoir atteindre le socket API de SPIRE Server. Le fournisseur sert le document de découverte et le JWKS via HTTPS. Terminez le TLS avec sa prise en charge ACME intégrée, ou placez-le derrière un équilibreur de charge qui le fait.

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}



Enregistrer la charge de travail

Chaque charge de travail qui appelle l'API Claude a besoin d'une entrée d'enregistrement SPIRE qui mappe ses sélecteurs d'exécution à un identifiant SPIFFE. Si la charge de travail est déjà enregistrée, notez son identifiant SPIFFE, que vous utiliserez dans le subject_prefix de la règle de fédération. Sinon, enregistrez-la. Pour un pod Kubernetes, les sélecteurs sont généralement l'espace de noms et le compte de service Kubernetes :

# Remplacez NODE_UID par l'UID du nœud :
#   kubectl get node <node-name> -o jsonpath='{.metadata.uid}'
spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Les charges de travail en dehors de Kubernetes utilisent des sélecteurs au niveau de l'hôte tels que unix:uid:1000 (unix:path est également disponible mais nécessite discover_workload_path = true dans la configuration de l'attesteur de charge de travail unix de l'agent). Les clusters exécutant spire-controller-manager peuvent déclarer des entrées avec la ressource personnalisée ClusterSPIFFEID au lieu d'appeler directement spire-server entry create.



Exécuter spiffe-helper

spiffe-helper est un utilitaire sidecar qui se connecte au socket de SPIRE Agent, récupère un JWT-SVID pour une audience donnée, l'écrit dans un fichier et le récupère à nouveau avant son expiration. L'assistant s'exécute en mode démon par défaut. L'exemple suivant définit explicitement daemon_mode = true.

agent_address = "/run/spire/sockets/agent.sock"
# The JWT-SVID file is written under cert_dir
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

Dans Kubernetes, exécutez spiffe-helper en tant que conteneur sidecar qui partage un volume emptyDir en mémoire (medium: Memory) avec votre conteneur d'application afin que le SVID porteur n'atterrisse jamais sur le disque du nœud. Montez le socket de SPIRE Agent depuis l'hôte dans le sidecar, montez le volume partagé à /var/run/secrets/anthropic.com dans les deux conteneurs, et définissez ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token sur le conteneur d'application. Sur les machines virtuelles et le bare-metal, exécutez spiffe-helper en tant que service système aux côtés de la charge de travail et pointez les deux vers un répertoire partagé.



Configurer Anthropic

Dans la Claude Console, ouvrez Settings → Workload identity, cliquez sur Connect workload et sélectionnez Custom OIDC. L'assistant vous guide à travers l'enregistrement de l'émetteur, la création d'un compte de service et la création d'une règle de fédération.

L'assistant crée ces ressources pour vous. Utilisez les valeurs suivantes, que vous les saisissiez dans l'assistant ou que vous les envoyiez à l'Admin API :

Émetteur de fédération : Enregistrez l'URL publique de l'OIDC Discovery Provider en mode discovery. Anthropic récupère /.well-known/openid-configuration à partir de cette URL et suit le jwks_uri renvoyé pour récupérer les clés de signature du domaine de confiance.

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

Si le fournisseur de découverte n'est pas accessible depuis l'internet public, récupérez le JWKS vous-même (curl https://oidc-discovery.prod.example.com/keys) et enregistrez l'émetteur avec "jwks": {"type": "inline", "keys": [...]} en utilisant le contenu du tableau keys renvoyé. En mode inline, l'issuer_url est uniquement comparé à la revendication iss du JWT-SVID. Anthropic ne tente jamais de l'atteindre.

Pour automatiser les mises à jour du JWKS sans exposer un point de terminaison de découverte public, configurez un plugin BundlePublisher de SPIRE Server (aws_s3, gcp_cloudstorage ou k8s_configmap) avec format = "jwks" pour pousser les clés de signature JWT vers un stockage externe à chaque rotation, puis mettez à jour les clés inline de l'émetteur via l'Admin API.

Règle de fédération : Faites correspondre le sub du JWT-SVID (l'identifiant SPIFFE) et l'aud que vous avez configuré spiffe-helper à demander. Les identifiants SPIFFE sont des chaînes URI et subject_prefix les compare comme du texte opaque, donc une valeur exacte ou une correspondance de préfixe avec * final fonctionnent toutes deux avec eux. Pour des motifs plus complexes, utilisez une condition CEL.

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

token_lifetime_seconds est la durée de vie du jeton d'accès Anthropic renvoyé par l'échange, pas celle du JWT-SVID. Le SDK actualise automatiquement le jeton d'accès.

Soyez aussi spécifique que la charge de travail le permet. N'assouplissez subject_prefix en spiffe://prod.example.com/ns/inference/* que si chaque charge de travail enregistrée sous ce chemin doit être mappée au même compte de service Anthropic. Ajoutez l'identifiant fdrl_... de la règle à la variable d'environnement ANTHROPIC_FEDERATION_RULE_ID de la charge de travail.



Acquérir et utiliser le jeton

Les SDK Anthropic peuvent soit lire le JWT-SVID à partir du fichier que spiffe-helper maintient, soit appeler directement la Workload API de SPIFFE via un callable fournisseur de jetons. Le chemin par fichier est l'intégration la plus simple et fonctionne dans tous les langages de SDK. Le chemin par callable supprime le sidecar mais nécessite un client Workload API SPIFFE dans le langage de votre application.

import anthropic

# Lit le JWT-SVID que spiffe-helper écrit dans
# ANTHROPIC_IDENTITY_TOKEN_FILE, ainsi que ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID et ANTHROPIC_WORKSPACE_ID.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))



Vérifier la configuration

Avant d'intégrer le SDK, récupérez un JWT-SVID directement depuis SPIRE Agent et confirmez que les revendications correspondent à ce que votre règle de fédération attend. Si vous utilisez une autre implémentation SPIFFE, récupérez un JWT-SVID avec sa CLI ou son client Workload API et décodez la charge utile de la même manière.

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

L'option -output json renvoie la réponse SVID et la réponse bundle sous forme de tableau JSON à deux éléments, donc jq -r '.[0].svids[0].svid' extrait le jeton brut. Sur les versions plus anciennes de SPIRE sans -output, la commande affiche à la place un bloc étiqueté. Dans ce cas, faites passer la sortie par défaut dans awk '/^[[:space:]]*eyJ/{print $1; exit}' pour extraire la ligne du jeton. Vérifiez que iss est l'URL de l'OIDC Discovery Provider que vous avez enregistrée, que sub est l'identifiant SPIFFE de la charge de travail et que aud contient https://api.anthropic.com. Exécutez ensuite l'exemple cURL de Acquérir et utiliser le jeton. Un échange réussi renvoie un access_token commençant par sk-ant-oat01-. En cas de 400 invalid_grant, consultez Dépanner un échange échoué. La cause la plus courante côté SPIRE est une incohérence entre le jwt_issuer de SPIRE Server et l'URL enregistrée comme émetteur de fédération.



Délimiter votre règle

Les conventions de chemin des identifiants SPIFFE sont définies par l'opérateur, donc le matcher subject_prefix de la règle de fédération doit refléter le schéma de chemin utilisé par vos entrées d'enregistrement. Les schémas courants incluent spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (la valeur par défaut émise par la ressource ClusterSPIFFEID dans spire-controller-manager) et spiffe://<trust-domain>/host/<hostname>/<service> pour les charges de travail sur machines virtuelles et bare-metal.

Verrouillez le bloc match de la règle à la portée la plus étroite qui convient à votre cas d'usage :

• Épingler à une seule charge de travail : Définissez subject_prefix sur l'identifiant SPIFFE complet sans * final.
• Toujours définir une audience : Exigez audience sur la règle et configurez spiffe-helper (ou l'appel à la Workload API) avec la même valeur afin que les SVID émis pour d'autres parties de confiance soient rejetés.
• Délimiter par segment de chemin : Utilisez spiffe://prod.example.com/ns/inference/* pour accorder l'accès à toutes les charges de travail enregistrées sous un espace de noms, et créez une règle et un compte de service Anthropic distincts par espace de noms plutôt que d'élargir une seule règle.
• Un émetteur par domaine de confiance : Chaque domaine de confiance SPIRE possède ses propres clés de signature et son propre OIDC Discovery Provider. Enregistrez chacun comme un émetteur de fédération distinct et liez les règles à l'émetteur qui possède les identifiants SPIFFE auxquels elles correspondent.



Prochaines étapes