Claude Platform Docs
AdministrationFournisseurs d'identité

Utiliser WIF avec Kubernetes

Authentifiez-vous auprès de l'API Claude depuis des clusters Kubernetes autogérés à l'aide de jetons de compte de service projetés.

Les clusters Kubernetes autogérés (kubeadm, k3s, OpenShift et les distributions sur site) signent des « JSON Web Tokens » (jetons web JSON), ou JWT, OIDC pour chaque pod via les projected service account tokens (jetons de compte de service projetés). Le serveur d'API du cluster agit en tant qu'é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 :

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

Prérequis

  • Une 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'indicateur --service-account-issuer configuré sur le serveur d'API. La plupart des distributions le 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 d'API.
  • L'un des éléments suivants afin 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 dans le chemin de montage et le renouvelle avant que expirationSeconds ne soit écoulé.

Pod
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 contient sub: "system:serviceaccount:inference:inference-worker" et aud: ["https://api.anthropic.com"].

Configurer Anthropic

Dans la Claude Console, ouvrez Settings → Workload identity, cliquez sur Connect workload et sélectionnez la tuile Kubernetes. L'assistant vous guide dans 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 : 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 :

cURL
kubectl get --raw /openid/v1/jwks

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

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks": {
    "type": "inline",
    "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 la joindre. Si votre émetteur est accessible publiquement, utilisez plutôt "jwks": {"type": "discovery"}.

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 précis que la charge de travail le permet. N'élargissez subject_prefix à system:serviceaccount:inference:* (le * final en fait une correspondance par préfixe) que si tous les comptes de service de l'espace de noms doivent être associés 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.

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

Un échange réussi renvoie un access_token commençant par sk-ant-oat01- et une valeur expires_in en secondes. Si l'échange échoue avec la réponse opaque 401 authentication_error (message Authentication failed), consultez la page d'historique d'authentification pour connaître le motif du refus et reportez-vous à Dépanner un échange échoué ; la cause la plus fréquente côté Kubernetes est une non-correspondance de clé JWKS (en mode inline, récupérez-la à nouveau avec kubectl get --raw /openid/v1/jwks et mettez à jour l'émetteur).

Restreindre la portée de votre règle

Verrouillez le bloc match de la règle sur la portée la plus étroite adaptée à votre cas d'utilisation :

  • Fixez l'espace de noms et le nom du compte de service : utilisez la valeur complète system:serviceaccount:<namespace>:<name> sans * final.
  • Définissez toujours 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 à audience par défaut soient rejetés.
  • Utilisez une règle distincte par espace de noms : créez une règle et un compte de service Anthropic distincts pour chaque espace de noms plutôt que d'élargir une seule règle.
  • Limitez 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

Was this page helpful?