Utilizzare WIF con Kubernetes

I cluster Kubernetes autogestiti (kubeadm, k3s, OpenShift e distribuzioni on-premises) firmano "JSON Web Tokens" (token web JSON), o JWT, OIDC per ogni pod tramite i projected service account tokens (token di service account proiettati). L'API server del cluster funge da issuer OIDC, e il claim sub di ciascun token segue il formato 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 utilizzano 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 Configurare Anthropic).
• Autorizzazione a creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.

Configurare 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 trascorra 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

Segui la procedura di configurazione per registrare un federation issuer, creare un service account Anthropic e creare una federation rule nella Claude Console. Utilizza questi valori specifici per Kubernetes.

Federation issuer: Molti cluster autogestiti utilizzano un URL dell'issuer come https://kubernetes.default.svc.cluster.local che non è raggiungibile dalla rete internet pubblica. Se questo è il caso del 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_source": "inline",
  "jwks_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, utilizza invece "jwks_source": "discovery" e ometti jwks_keys.

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 in base al workload. 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 utilizzare 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 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Verificare 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 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).

Definire 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: Utilizza 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.
• Utilizza una regola separata per namespace: Crea una regola distinta e un service account Anthropic per ciascun 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 separato e associa le regole solo a quell'issuer.

Passaggi successivi

• Workload Identity Federation: concetti, il 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.