WIF mit Kubernetes verwenden

Selbstverwaltete Kubernetes-Cluster (kubeadm, k3s, OpenShift und On-Premises-Distributionen) signieren OIDC JSON Web Tokens (JWTs) für jeden Pod über projizierte Service-Account-Tokens. Der API-Server des Clusters fungiert als OIDC-Issuer, und der sub-Claim jedes Tokens folgt der Form system:serviceaccount:<namespace>:<service-account>. Du findest die Issuer-URL deines Clusters, indem du dessen Discovery-Dokument liest:

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



Voraussetzungen

• Vertrautheit mit WIF-Konzepten: Service Accounts, Federation Issuers und Federation Rules.
• Ein Kubernetes-Cluster, bei dem das Flag --service-account-issuer auf dem API-Server konfiguriert ist. Die meisten Distributionen setzen dies standardmäßig; kubeadm-Cluster verwenden typischerweise https://kubernetes.default.svc.cluster.local. Dein Plattform-Team kann den Wert bestätigen, wenn du keinen direkten Zugriff auf die API-Server-Konfiguration hast.
• Eine der folgenden Voraussetzungen, damit Anthropic Token-Signaturen validieren kann:
  • Der JWKS-Endpunkt des Issuers ist über HTTPS auf Port 443 aus dem öffentlichen Internet erreichbar, oder
  • Du kannst das JWKS aus dem Inneren des Clusters abrufen und im inline-Modus registrieren (behandelt in Anthropic konfigurieren).
• Berechtigung zum Erstellen von Service Accounts, Federation Issuers und Federation Rules in der Claude Console für deine Anthropic-Organisation.



Kubernetes konfigurieren

Projiziere ein Service-Account-Token in deinen Pod mit der Audience und Lebensdauer, die deine Federation Rule erwartet. Die serviceAccountToken-Projektion schreibt ein frisches JWT in den Mount-Pfad und rotiert es, bevor expirationSeconds abläuft.

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

Das für diesen Pod ausgestellte Token trägt sub: "system:serviceaccount:inference:inference-worker" und aud: ["https://api.anthropic.com"].



Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die Kachel Kubernetes. Der Assistent führt dich durch die Registrierung des Issuers, die Erstellung eines Service Accounts und die Erstellung einer Federation Rule.

Der Assistent erstellt diese Ressourcen für dich. Verwende die folgenden Werte, unabhängig davon, ob du sie im Assistenten eingibst oder an die Admin API sendest:

Federation Issuer: Viele selbstverwaltete Cluster verwenden eine Issuer-URL wie https://kubernetes.default.svc.cluster.local, die nicht aus dem öffentlichen Internet erreichbar ist. Wenn das auf deinen Cluster zutrifft, wähle die inline-JWKS-Quelle und füge die Schlüssel des Clusters ein. Rufe sie aus dem Inneren des Clusters ab:

kubectl get --raw /openid/v1/jwks

Konfiguriere dann den Issuer mit dem Inhalt des zurückgegebenen keys-Arrays (nicht mit dem umgebenden {"keys": [...]}-Wrapper):

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

Im inline-Modus wird die issuer_url nur mit dem iss-Claim des JWT verglichen; Anthropic versucht niemals, sie zu erreichen. Wenn dein Issuer öffentlich erreichbar ist, verwende stattdessen "jwks": {"type": "discovery"}.

Federation Rule: Gleiche den sub-Claim des Service Accounts und die Audience ab, die du auf dem projizierten Token gesetzt hast.

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

Sei so spezifisch, wie es der Workload erlaubt. Lockere subject_prefix nur dann auf system:serviceaccount:inference:* (das abschließende * macht daraus einen Präfix-Match), wenn jeder Service Account im Namespace demselben Anthropic Service Account zugeordnet werden soll. Füge die fdrl_...-ID der Regel zur Umgebungsvariable ANTHROPIC_FEDERATION_RULE_ID deines Pods hinzu.



Token beziehen und verwenden

Die Pod-Spezifikation in Kubernetes konfigurieren setzt ANTHROPIC_IDENTITY_TOKEN_FILE auf den projizierten Mount-Pfad, zusammen mit ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID und ANTHROPIC_WORKSPACE_ID. Wenn diese gesetzt sind, liest das SDK das Token bei jedem Austausch von der Festplatte und aktualisiert das Anthropic-Access-Token automatisch.

import anthropic

# Liest ANTHROPIC_IDENTITY_TOKEN_FILE, ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID und ANTHROPIC_WORKSPACE_ID
# aus der Umgebung des Pods.
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"))



Einrichtung überprüfen

Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Bei 400 invalid_grant siehe Fehlgeschlagenen Austausch beheben; die häufigste Ursache auf Kubernetes-Seite ist eine JWKS-Schlüssel-Diskrepanz (für den inline-Modus: rufe das JWKS mit kubectl get --raw /openid/v1/jwks erneut ab und aktualisiere den Issuer).



Regel eingrenzen

Beschränke den match-Block der Regel auf den engsten Umfang, der zu deinem Anwendungsfall passt:

• Namespace und Service-Account-Namen festlegen: Verwende den vollständigen Wert system:serviceaccount:<namespace>:<name> ohne abschließendes *.
• Immer eine Audience setzen: Verlange audience in der Regel und setze denselben Wert in der serviceAccountToken-Projektion des Pods, damit Default-Audience-Tokens abgelehnt werden.
• Eine separate Regel pro Namespace verwenden: Erstelle für jeden Namespace eine eigene Regel und einen eigenen Anthropic Service Account, anstatt eine Regel zu erweitern.
• Inline-JWKS-Issuer auf einen Cluster beschränken: Wenn mehrere Cluster eine Issuer-URL teilen, registriere das JWKS jedes Clusters als eigenen Federation Issuer und binde Regeln nur an diesen Issuer.



Nächste Schritte

• Workload Identity Federation: Konzepte, der Token-Austausch-Ablauf und SDK-Konfigurationsoptionen.
• WIF-Referenz: Umgebungsvariablen, JWKS-Quellmodi und Regel-Match-Modi.