Usare WIF con Kubernetes

I cluster Kubernetes autogestiti (kubeadm, k3s, OpenShift e distribuzioni on-premises) firmano JSON Web Token (JWT) OIDC per ogni pod tramite i projected service account token (token di service account proiettati). L'API server del cluster agisce come issuer (emittente) OIDC, e il claim sub di ogni token segue la forma system:serviceaccount:<namespace>:<service-account>. Puoi trovare l'URL dell'issuer del tuo cluster leggendo il suo documento di discovery:

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

Prerequisiti

• Familiarità con i concetti di WIF: service account, federation issuer e federation rule.
• Un cluster Kubernetes con il flag --service-account-issuer configurato sull'API server. La maggior parte delle distribuzioni lo imposta per impostazione predefinita; i cluster kubeadm usano tipicamente https://kubernetes.default.svc.cluster.local. Il tuo team di piattaforma può confermare il valore se non hai accesso diretto alla configurazione dell'API server.
• Una delle seguenti condizioni, affinché Anthropic possa validare le firme dei token:
  • L'endpoint JWKS dell'issuer è raggiungibile dalla rete internet pubblica tramite HTTPS sulla porta 443, oppure
  • Puoi recuperare il JWKS dall'interno del cluster e registrarlo in modalità inline (trattata in Configurare Anthropic).
• Il permesso di creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.

Configurare Kubernetes

Proietta un service account token nel tuo pod con l'audience e la durata che la tua federation rule si aspetta. La proiezione serviceAccountToken scrive un nuovo JWT nel percorso di mount e lo ruota prima che trascorrano expirationSeconds.

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

Il token emesso per questo pod contiene sub: "system:serviceaccount:inference:inference-worker" e aud: ["https://api.anthropic.com"].

Configurare Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro Kubernetes. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un service account e nella creazione di una federation rule.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Federation issuer: Molti cluster autogestiti usano un URL dell'issuer come https://kubernetes.default.svc.cluster.local che non è raggiungibile dalla rete internet pubblica. Se questo vale per il tuo cluster, scegli la sorgente JWKS inline e incolla le chiavi del cluster. Recuperale dall'interno del cluster:

kubectl get --raw /openid/v1/jwks

Quindi configura l'issuer con il contenuto dell'array keys restituito (non il wrapper {"keys": [...]} che lo racchiude):

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

In modalità inline l'issuer_url viene solo confrontato con il claim iss del JWT; Anthropic non tenta mai di raggiungerlo. Se il tuo issuer è raggiungibile pubblicamente, usa invece "jwks": {"type": "discovery"}.

Federation rule: Fai corrispondere il claim sub del service account e l'audience che hai impostato sul token proiettato.

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

Sii specifico quanto il workload lo consente. Allenta subject_prefix a system:serviceaccount:inference:* (il * finale lo rende una corrispondenza per prefisso) solo se ogni service account nel namespace deve essere mappato allo stesso service account Anthropic. Aggiungi l'ID fdrl_... della regola alla variabile d'ambiente ANTHROPIC_FEDERATION_RULE_ID del tuo pod.

Acquisire e usare il token

La specifica del pod in Configurare Kubernetes imposta ANTHROPIC_IDENTITY_TOKEN_FILE sul percorso di mount proiettato, insieme a ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID. Con queste variabili impostate, l'SDK legge il token dal disco a ogni scambio e aggiorna automaticamente l'access token Anthropic.

import anthropic

# Legge ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e ANTHROPIC_WORKSPACE_ID
# dall'ambiente del 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"))

Verificare la configurazione

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia delle autenticazioni per il motivo del rifiuto e consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato Kubernetes è una mancata corrispondenza delle chiavi JWKS (per la modalità inline, recuperale nuovamente con kubectl get --raw /openid/v1/jwks e aggiorna l'issuer).

Delimitare l'ambito della regola

Limita il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

• Fissa namespace e nome del service account: Usa il valore completo system:serviceaccount:<namespace>:<name> senza * finale.
• Imposta sempre un'audience: Richiedi audience nella regola e imposta lo stesso valore nella proiezione serviceAccountToken del pod, in modo che i token con audience predefinita vengano rifiutati.
• Usa una regola separata per ogni namespace: Crea una regola e un service account Anthropic distinti per ogni namespace anziché ampliare una singola regola.
• Limita gli issuer con JWKS inline a un solo cluster: Quando più cluster condividono un URL dell'issuer, registra il JWKS di ciascun cluster come federation issuer a sé stante e associa le regole solo a quell'issuer.

Passaggi successivi

• Workload Identity Federation: concetti, flusso di scambio dei token e opzioni di configurazione dell'SDK.
• Riferimento WIF: variabili d'ambiente, modalità di sorgente JWKS e modalità di corrispondenza delle regole.