Utiliser WIF avec SPIFFE

SPIFFE est la norme CNCF pour l'attribution d'identité 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. La fédération fonctionne soit via un document de découverte OIDC à une URL HTTPS publique (mode discovery ; voir les 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 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 outre iss et iat, qu'aucune des deux n'est imposée par la spécification JWT-SVID ; configurez donc 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. Pour une liste à jour, consultez Commercial software that implements SPIFFE sur le site du projet 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 OIDC standard est le SPIRE OIDC Discovery Provider, un utilitaire 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 en tant qu'é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

• 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, le OIDC Discovery Provider) fonctionnant avec un point de terminaison HTTPS accessible publiquement, ou le JWKS exporté pour l'enregistrement inline.
• Votre émetteur SPIFFE configuré pour définir la revendication iss sur les JWT-SVID à 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 ; les X.509-SVID ne sont pas utilisés.
• 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 paramètre jwt_audience de spiffe-helper, dans l'appel FetchJWTSVID de la Workload API, et dans 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 de JWT-SVID selon sa propre documentation, puis continuez à Configurer Anthropic.

Si vous exécutez déjà SPIRE avec le OIDC Discovery Provider, la fédération avec Anthropic nécessite trois éléments 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 éléments. Les extraits de configuration ne montrent que les paramètres pertinents pour la fédération Anthropic ; ce ne sont pas des configurations de déploiement SPIRE complètes.

Vérifier l'émetteur JWT

Anthropic valide un JWT-SVID en comparant 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 dans chaque JWT-SVID émis) et la liste domains du OIDC Discovery Provider (qui détermine l'hôte depuis lequel 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é pour l'émetteur de fédération (1 heure par défaut ; voir Règles de validation). Cette vérification s'applique à toute implémentation SPIFFE, pas seulement à SPIRE, donc maintenez default_jwt_svid_ttl (ou toute substitution par entrée) à une valeur inférieure ou égale à ce maximum.

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

Dans la configuration du 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 TLS avec son support ACME intégré ou placez devant lui un équilibreur de charge qui s'en charge.

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 associe ses sélecteurs d'exécution à un identifiant SPIFFE. Si la charge de travail est déjà enregistrée, notez son identifiant SPIFFE ; vous l'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 le namespace et le compte de service Kubernetes :

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 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 expiration. L'utilitaire s'exécute en mode démon par défaut ; l'exemple ci-dessous définit explicitement daemon_mode = true.

agent_address = "/run/spire/sockets/agent.sock"
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 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 VM et le bare metal, exécutez spiffe-helper en tant que service système aux côtés de la charge de travail et faites pointer les deux vers un répertoire partagé.

Configurer Anthropic

Suivez le guide de configuration pour enregistrer un émetteur de fédération, créer un compte de service Anthropic et créer une règle de fédération dans la Claude Console. Utilisez ces valeurs spécifiques à SPIFFE.

Émetteur de fédération : Enregistrez l'URL publique du OIDC Discovery Provider en mode discovery. Anthropic récupère /.well-known/openid-configuration depuis cette URL et suit le jwks_uri retourné 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 vous-même le JWKS (curl https://oidc-discovery.prod.example.com/keys) et enregistrez l'émetteur avec "jwks": {"type": "inline", "keys": [...]} en utilisant le contenu du tableau keys retourné. En mode inline, le issuer_url est uniquement comparé à la revendication iss du JWT-SVID ; Anthropic ne tente jamais de l'atteindre.

Pour automatiser les mises à jour 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 synchronisez-les dans les clés inline de l'émetteur.

Règle de fédération : Faites correspondre le sub du JWT-SVID (l'identifiant SPIFFE) et le aud que vous avez configuré spiffe-helper à demander. Les identifiants SPIFFE sont des chaînes URI et subject_prefix les compare en tant que texte opaque, donc une valeur exacte ou une correspondance de préfixe avec * final fonctionnent toutes deux. 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
}

Soyez aussi spécifique que la charge de travail le permet. N'élargissez subject_prefix à spiffe://prod.example.com/ns/inference/* que si chaque charge de travail enregistrée sous ce chemin doit être associé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 depuis le fichier que spiffe-helper maintient, soit appeler directement la Workload API SPIFFE via un callable fournisseur de jeton. Le chemin de fichier est l'intégration la plus simple et fonctionne dans tous les langages SDK ; le chemin callable supprime le sidecar mais nécessite un client Workload API SPIFFE dans le langage de votre application.

Vérifier la configuration

Avant de câbler 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 son 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 retourne 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 anciennes versions de SPIRE sans -output, la commande affiche un bloc étiqueté à la place ; dans ce cas, redirigez la sortie par défaut via awk '/^[[:space:]]*eyJ/{print $1; exit}' pour extraire la ligne du jeton. Vérifiez que iss est l'URL du 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 retourne 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 que vos entrées d'enregistrement utilisent. 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 VM 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 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 à chaque charge de travail enregistrée sous un namespace, et créez une règle et un compte de service Anthropic distincts par namespace 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.

Étapes suivantes

• Workload Identity Federation : concepts, flux d'échange de jetons et options de configuration du SDK.
• Référence WIF : variables d'environnement, modes de source JWKS et modes de correspondance des règles.
• Utiliser WIF avec Kubernetes : pour les clusters qui utilisent des jetons de compte de service projetés natifs au lieu de SPIRE.