Utiliser WIF avec Kubernetes

Les clusters Kubernetes autogérés (kubeadm, k3s, OpenShift et distributions sur site) signent des « JSON Web Tokens » (jetons web JSON), ou JWT, OIDC pour chaque pod via les jetons de compte de service projetés. Le serveur API du cluster agit comme émetteur OIDC, et la revendication sub de chaque jeton suit la forme system:serviceaccount:<namespace>:<service-account>. Vous pouvez trouver l'URL de l'émetteur de votre cluster en lisant son document de découverte :

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

Prérequis

• Familiarité avec les concepts WIF : comptes de service, émetteurs de fédération et règles de fédération.
• Un cluster Kubernetes avec l'option --service-account-issuer configurée sur le serveur API. La plupart des distributions la définissent par défaut ; les clusters kubeadm utilisent généralement https://kubernetes.default.svc.cluster.local. Votre équipe plateforme peut confirmer la valeur si vous n'avez pas d'accès direct à la configuration du serveur API.
• L'une des conditions suivantes pour qu'Anthropic puisse valider les signatures des jetons :
  • Le point de terminaison JWKS de l'émetteur est accessible depuis l'internet public via HTTPS sur le port 443, ou
  • Vous pouvez récupérer le JWKS depuis l'intérieur du cluster et l'enregistrer en mode inline (traité dans Configurer Anthropic).
• 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.

Configurer Kubernetes

Projetez un jeton de compte de service dans votre pod avec l'audience et la durée de vie attendues par votre règle de fédération. La projection serviceAccountToken écrit un nouveau JWT au chemin de montage et le renouvelle avant que expirationSeconds ne s'écoule.

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

Le jeton émis pour ce pod porte sub: "system:serviceaccount:inference:inference-worker" et aud: ["https://api.anthropic.com"].

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

Émetteur de fédération : De nombreux clusters autogérés utilisent une URL d'émetteur telle que https://kubernetes.default.svc.cluster.local qui n'est pas accessible depuis l'internet public. Si c'est le cas de votre cluster, choisissez la source JWKS inline et collez les clés du cluster. Récupérez-les depuis l'intérieur du cluster :

kubectl get --raw /openid/v1/jwks

Configurez ensuite l'émetteur avec le contenu du tableau keys retourné (et non l'enveloppe {"keys": [...]} qui l'entoure) :

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

En mode inline, l'issuer_url est uniquement comparée à la revendication iss du JWT ; Anthropic ne tente jamais de l'atteindre. Si votre émetteur est accessible publiquement, utilisez plutôt "jwks_source": "discovery" et omettez jwks_keys.

Règle de fédération : Faites correspondre la revendication sub du compte de service et l'audience que vous avez définie sur le jeton projeté.

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-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'assouplissez subject_prefix à system:serviceaccount:inference:* (le * final en fait une correspondance de préfixe) que si chaque compte de service du namespace doit être mappé au même compte de service Anthropic. Ajoutez l'ID fdrl_... de la règle à la variable d'environnement ANTHROPIC_FEDERATION_RULE_ID de votre pod.

Acquérir et utiliser le jeton

La spécification de pod dans Configurer Kubernetes définit ANTHROPIC_IDENTITY_TOKEN_FILE sur le chemin de montage projeté, ainsi que ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID et ANTHROPIC_WORKSPACE_ID. Une fois ces éléments en place, le SDK lit le jeton depuis le disque à chaque échange et actualise automatiquement le jeton d'accès Anthropic.

import anthropic

# Lit ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID et ANTHROPIC_WORKSPACE_ID
# depuis l'environnement du pod.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Vérifier la configuration

Un échange réussi retourne un access_token commençant par sk-ant-oat01- et une valeur expires_in en secondes. En cas de 400 invalid_grant, consultez Dépanner un échange échoué ; la cause la plus courante côté Kubernetes est une incompatibilité de clé JWKS (pour le mode inline, récupérez à nouveau avec kubectl get --raw /openid/v1/jwks et mettez à jour l'émetteur).

Délimiter votre règle

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

• Épingler le namespace et le nom du compte de service : Utilisez la valeur complète system:serviceaccount:<namespace>:<name> sans * final.
• Toujours définir une audience : Exigez audience sur la règle et définissez la même valeur sur la projection serviceAccountToken du pod afin que les jetons d'audience par défaut soient rejetés.
• Utiliser une règle distincte par namespace : Créez une règle et un compte de service Anthropic distincts pour chaque namespace plutôt que d'élargir une seule règle.
• Limiter les émetteurs JWKS inline à un seul cluster : Lorsque plusieurs clusters partagent une URL d'émetteur, enregistrez le JWKS de chaque cluster comme son propre émetteur de fédération et liez les règles uniquement à cet émetteur.

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