Usa 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 token di service account proiettati. L'API server del cluster agisce come issuer 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 convalidare 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 (trattato in Configura Anthropic).
• Autorizzazione a creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.



Configura Kubernetes

Proietta un token di service account 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 expirationSeconds scada.

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"].



Configura 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 confrontato solo 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 il più specifico possibile per quanto consentito dal workload. Allenta subject_prefix a system:serviceaccount:inference:* (l'* 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.



Acquisisci e usa il token

La specifica del pod in Configura 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 questi valori impostati, l'SDK legge il token dal disco a ogni scambio e aggiorna automaticamente il token di accesso 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"))



Verifica la configurazione

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. In caso di 400 invalid_grant, consulta Risolvere i problemi di uno scambio non riuscito; la causa più comune lato Kubernetes è una mancata corrispondenza delle chiavi JWKS (per la modalità inline, recuperale di nuovo con kubectl get --raw /openid/v1/jwks e aggiorna l'issuer).



Limita l'ambito della regola

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

• Fissa il namespace e il 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 sulla 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 ogni cluster come federation issuer separato e associa le regole solo a quell'issuer.



Prossimi passi

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