Claude Platform Docs
AdminIdentitätsanbieter

WIF mit Kubernetes verwenden

Authentifiziere dich gegenüber der Claude API aus selbstverwalteten Kubernetes-Clustern mithilfe projizierter Service-Account-Token.

Selbstverwaltete Kubernetes-Cluster (kubeadm, k3s, OpenShift und On-Premises-Distributionen) signieren OIDC JSON Web Tokens (JWTs) für jeden Pod über projected service account tokens (projizierte Service-Account-Token). 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 sein Discovery-Dokument ausliest:

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

Voraussetzungen

  • Vertrautheit mit den 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 es 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 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 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, das Erstellen eines Service-Accounts und das Erstellen einer Federation-Regel.

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 aus dem öffentlichen Internet nicht erreichbar ist. Wenn das auf deinen Cluster zutrifft, wähle die JWKS-Quelle inline 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": {
    "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 nie, sie zu erreichen. Wenn dein Issuer öffentlich erreichbar ist, verwende stattdessen "jwks": {"type": "discovery"}.

Federation-Regel: 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-Abgleich), wenn jeder Service-Account im Namespace auf denselben Anthropic-Service-Account abgebildet 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. Sind diese gesetzt, liest das SDK das Token bei jedem Austausch von der Festplatte und erneuert das Anthropic-Zugriffstoken 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. Wenn der Austausch mit der undurchsichtigen 401-authentication_error-Antwort (Meldung Authentication failed) fehlschlägt, prüfe die Seite mit dem Authentifizierungsverlauf auf den Ablehnungsgrund und siehe Fehlerbehebung bei einem fehlgeschlagenen Austausch; die häufigste Ursache auf Kubernetes-Seite ist eine Nichtübereinstimmung der JWKS-Schlüssel (im inline-Modus erneut mit kubectl get --raw /openid/v1/jwks abrufen und den Issuer aktualisieren).

Geltungsbereich deiner Regel festlegen

Beschränke den match-Block der Regel auf den engsten Geltungsbereich, 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-Token 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 auszuweiten.
  • 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

Was this page helpful?