WIF mit Kubernetes verwenden

Selbstverwaltete Kubernetes-Cluster (kubeadm, k3s, OpenShift und On-Premises-Distributionen) signieren OIDC „JSON Web Tokens" (JSON-Web-Tokens), oder 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 dem Format system:serviceaccount:<namespace>:<service-account>. Du kannst die Issuer-URL deines Clusters ermitteln, indem du sein Discovery-Dokument ausliest:

cURL

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

Der auf dieser Seite beschriebene Mechanismus (projiziertes Service-Account-Token, Cluster-API-Server als OIDC-Issuer) ist nativ in Kubernetes selbst integriert und liegt daher jeder Kubernetes-Distribution zugrunde. Wenn du einen verwalteten Kubernetes-Dienst nutzt, erklären die Cloud-Provider-Leitfäden, wo du die vom Provider verwaltete Issuer-URL findest: AWS (EKS), Google Cloud (GKE) oder Azure (AKS). Wenn dein Cluster SPIRE ausführt, ist der SPIRE OIDC Discovery Provider der Issuer anstelle des Cluster-API-Servers; siehe SPIFFE. Für jede andere Distribution oder einen dort nicht aufgeführten verwalteten Provider folge diesem Leitfaden und verwende die Issuer-URL, die dein Cluster meldet.

Voraussetzungen

Vertrautheit mit WIF-Konzepten: Service-Accounts, Federation-Issuer und Federation-Regeln.
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, falls du keinen direkten Zugriff auf die API-Server-Konfiguration hast.
Eine der folgenden Optionen, damit Anthropic Token-Signaturen validieren kann:
- Der JWKS-Endpunkt des Issuers ist aus dem öffentlichen Internet über HTTPS auf Port 443 erreichbar, oder
- Du kannst das JWKS aus dem Cluster heraus abrufen und im inline-Modus registrieren (behandelt in Anthropic konfigurieren).
Berechtigung zum Erstellen von Service-Accounts, Federation-Issuern und Federation-Regeln in der Claude Console für deine Anthropic-Organisation.

Kubernetes konfigurieren

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

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

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

Anthropic konfigurieren

Folge der Einrichtungsanleitung, um einen Federation-Issuer zu registrieren, einen Anthropic-Service-Account zu erstellen und eine Federation-Regel in der Claude Console anzulegen. Verwende dabei diese Kubernetes-spezifischen Werte.

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 Cluster heraus ab:

cURL

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_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

Im inline-Modus wird die issuer_url nur mit dem iss-Claim des JWT verglichen; Anthropic versucht nie, sie zu erreichen. Wenn dein Issuer öffentlich erreichbar ist, verwende stattdessen "jwks_source": "discovery" und lasse jwks_keys weg.

Bei inline-Schlüsseln bist du dafür verantwortlich, den Issuer zu aktualisieren, wenn der Cluster seinen Service-Account-Signaturschlüssel rotiert. Rotation ist selten (typischerweise nur bei Cluster-Upgrades), aber Token-Austausche schlagen mit einem Signaturfehler fehl, bis du das neue JWKS hochlädst.

Federation-Regel: Matche den sub-Claim des Service-Accounts und die Audience, 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 abrufen 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 erneuert das Anthropic-Zugriffstoken automatisch.

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 die Schlüssel erneut mit kubectl get --raw /openid/v1/jwks ab und aktualisiere den Issuer).

Regel eingrenzen

Ein subject_prefix von system:serviceaccount:* matcht jeden Service-Account im Cluster, sodass jeder Pod ein föderiertes Anthropic-Token erhalten kann. Ohne einen audience-Matcher matcht die Regel auch die Default-Audience-Tokens des Clusters, die bereits in jeden Pod projiziert werden.

Beschränke den match-Block der Regel auf den engsten Bereich, 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: Fordere audience in der Regel an 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 dieselbe 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.

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