WIF mit SPIFFE verwenden

SPIFFE ist der CNCF-Standard für die Ausstellung von Identitäten an Workloads. SPIRE ist seine Open-Source-Referenzimplementierung, und mehrere kommerzielle Produkte stellen ebenfalls SPIFFE-konforme Identitäten aus. Anthropic föderiert mit jeder SPIFFE-Implementierung, die OIDC-kompatible JWT-SVIDs ausgibt. Eine aktuelle Liste der Implementierungen findest du unter Commercial software that implements SPIFFE auf der Website des SPIFFE-Projekts.

Die Föderation funktioniert entweder über ein OIDC-Discovery-Dokument unter einer öffentlichen HTTPS-URL (discovery-Modus, vorbehaltlich der URL-Einschränkungen) oder durch die direkte Registrierung des JWKS (inline-Modus).

Die JWT-SVID-Spezifikation definiert sub als die SPIFFE-ID des Workloads, und die SPIFFE Workload API verlangt, dass der Aufrufer aud zum Zeitpunkt des Abrufs angibt, sodass diese Claims über alle Implementierungen hinweg gleich sind. Anthropic verlangt zusätzlich iss und iat, von denen keines durch die JWT-SVID-Spezifikation vorgeschrieben ist. Konfiguriere deine Implementierung daher so, dass beide gesetzt werden (in SPIRE ist iss die Server-Einstellung jwt_issuer und iat wird automatisch gesetzt). Sobald diese vorhanden sind, gelten die Abschnitte Anthropic konfigurieren, Token beziehen und verwenden und Regel eingrenzen dieses Leitfadens für jede SPIFFE-Implementierung.

SPIFFE weist jedem Workload eine stabile Identitäts-URI der Form spiffe://<trust-domain>/<path> zu, und SPIRE stellt diese Identität bei Bedarf als JWT-SVID über die Workload API aus. Ein JWT-SVID ist ein gewöhnliches signiertes JWT, dessen sub-Claim die SPIFFE-ID des Workloads ist und dessen aud-Claim vom Workload zum Zeitpunkt des Abrufs angegeben wird.

Die Brücke von einer SPIRE-Trust-Domain zu Standard-OIDC ist der SPIRE OIDC Discovery Provider, ein eigenständiger Helfer, der /.well-known/openid-configuration und einen JWKS-Endpunkt für die JWT-Signaturschlüssel der Trust-Domain veröffentlicht. Mit laufendem Discovery Provider wird ein JWT-SVID wie jedes andere OIDC-Token validiert: Registriere die Discovery-URL als Federation Issuer, schreibe eine Federation Rule, die auf die SPIFFE-ID des Workloads passt, und lasse den Workload sein JWT-SVID am Token-Exchange-Endpunkt von Anthropic vorlegen.

Die Beispiele auf dieser Seite verwenden SPIRE und gelten überall dort, wo SPIRE Agent läuft: Kubernetes-Pods, virtuelle Maschinen und Bare-Metal-Hosts.



Voraussetzungen

• Vertrautheit mit den WIF-Konzepten: Service Accounts, Federation Issuers und Federation Rules.
• Ein SPIFFE-Deployment mit ausgestellten Workload-Identitäten (die Beispiele auf dieser Seite verwenden SPIRE Server und Agent) sowie Registrierungseinträge für die Workloads, die die Claude API aufrufen müssen.
• Ein OIDC-Discovery-Endpunkt für die Trust-Domain (in SPIRE der OIDC Discovery Provider), der mit einem öffentlich erreichbaren HTTPS-Endpunkt läuft, oder das für die inline-Registrierung exportierte JWKS.
• Dein SPIFFE-Aussteller ist so konfiguriert, dass der iss-Claim auf JWT-SVIDs auf den Wert gesetzt wird, den du als issuer_url des Federation Issuers registrieren wirst. Im discovery-Modus ist dies die öffentliche URL des Discovery-Endpunkts (in SPIRE die Server-Einstellung jwt_issuer).
• JWT-SVIDs sind für deine Workloads verfügbar. WIF akzeptiert ausschließlich JWT-SVIDs, keine X.509-SVIDs.
• Berechtigung zum Erstellen von Service Accounts, Federation Issuers und Federation Rules in der Claude Console für deine Anthropic-Organisation.

Der Audience-Wert, der beim Abrufen eines JWT-SVID angefordert werden muss, ist immer https://api.anthropic.com. Verwende diesen Wert in der jwt_audience von spiffe-helper, im Workload-API-Aufruf FetchJWTSVID und im audience-Matcher der Federation Rule.



SPIRE konfigurieren

Die Anweisungen in diesem Abschnitt sind SPIRE-spezifisch. Wenn du einen anderen SPIFFE-Aussteller verwendest, konfiguriere dessen OIDC-Discovery-Endpunkt und den JWT-SVID-Abruf gemäß dessen eigener Dokumentation und fahre dann bei Anthropic konfigurieren fort.

Wenn du SPIRE bereits mit dem OIDC Discovery Provider betreibst, erfordert die Föderation mit Anthropic drei Dinge auf der SPIRE-Seite: einen jwt_issuer, der mit der Discovery-URL übereinstimmt, einen Registrierungseintrag für den Workload, der die Claude API aufrufen wird, und eine Möglichkeit für diesen Workload, ein JWT-SVID mit der Anthropic-Audience abzurufen. Die folgenden Unterabschnitte führen durch jeden Schritt. Die Konfigurationsausschnitte zeigen nur die für die Anthropic-Föderation relevanten Einstellungen, keine vollständigen SPIRE-Deployment-Konfigurationen.



JWT-Issuer überprüfen

Anthropic validiert ein JWT-SVID, indem es dessen iss-Claim mit einem registrierten Federation Issuer abgleicht und das JWKS aus dem Discovery-Dokument dieses Issuers abruft. Zwei SPIRE-Einstellungen müssen auf dieselbe URL verweisen: jwt_issuer von SPIRE Server (das zum iss-Claim in jedem ausgestellten JWT-SVID wird) und die domains-Liste des OIDC Discovery Providers (die den Host bestimmt, von dem das Discovery-Dokument und das JWKS ausgeliefert werden). Diese gemeinsame URL ist das, was du bei Anthropic registrierst.

Die Trust-Domain und die Issuer-URL sind unabhängig voneinander. Die Trust-Domain (spiffe://prod.example.com) begrenzt den sub-Claim. Die Issuer-URL (https://oidc-discovery.prod.example.com) ist der Ort, von dem Anthropic die Signaturschlüssel abruft. Sie müssen keinen gemeinsamen Hostnamen haben.

Bestätige, dass jwt_issuer in der Konfiguration von SPIRE Server gesetzt ist und auf die öffentliche URL des Discovery Providers zeigt. Das folgende Beispiel zeigt auch eine Standard-Lebensdauer für JWT-SVIDs. Der eingebaute Standardwert von SPIRE beträgt 5 Minuten, was kurz genug ist, dass eine kontinuierliche Rotation erforderlich ist (siehe spiffe-helper ausführen). Der Token-Exchange-Endpunkt von Anthropic lehnt jedes Identity-Token ab, dessen Lebensdauer das konfigurierte Maximum des Federation Issuers überschreitet, das standardmäßig 1 Stunde beträgt (siehe Validierungsregeln). Diese Prüfung gilt für jede SPIFFE-Implementierung, nicht nur für SPIRE. Halte daher default_jwt_svid_ttl (oder jede Überschreibung pro Eintrag) auf oder unter diesem Maximum.

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

In der Konfiguration des OIDC Discovery Providers muss derselbe Hostname unter domains erscheinen, und der Provider muss den API-Socket von SPIRE Server erreichen können. Der Provider liefert das Discovery-Dokument und das JWKS über HTTPS aus. Terminiere TLS mit seiner eingebauten ACME-Unterstützung oder setze einen Load Balancer davor, der dies übernimmt.

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}



Workload registrieren

Jeder Workload, der die Claude API aufruft, benötigt einen SPIRE-Registrierungseintrag, der seine Laufzeit-Selektoren einer SPIFFE-ID zuordnet. Wenn der Workload bereits registriert ist, notiere dir seine SPIFFE-ID, die du im subject_prefix der Federation Rule verwendest. Falls nicht, registriere ihn. Für einen Kubernetes-Pod sind die Selektoren typischerweise der Namespace und der Kubernetes-Service-Account:

# Ersetze NODE_UID durch die UID des Nodes:
#   kubectl get node <node-name> -o jsonpath='{.metadata.uid}'
spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Workloads außerhalb von Kubernetes verwenden Host-Level-Selektoren wie unix:uid:1000 (unix:path ist ebenfalls verfügbar, erfordert aber discover_workload_path = true in der Konfiguration des Unix-Workload-Attestors des Agents). Cluster, die spire-controller-manager ausführen, können Einträge mit der Custom Resource ClusterSPIFFEID deklarieren, anstatt spire-server entry create direkt aufzurufen.



spiffe-helper ausführen

spiffe-helper ist ein Sidecar-Utility, das sich mit dem SPIRE-Agent-Socket verbindet, ein JWT-SVID für eine bestimmte Audience abruft, es in eine Datei schreibt und es vor Ablauf erneut abruft. Der Helper läuft standardmäßig im Daemon-Modus. Das folgende Beispiel setzt daemon_mode = true explizit.

agent_address = "/run/spire/sockets/agent.sock"
# The JWT-SVID file is written under cert_dir
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

In Kubernetes führst du spiffe-helper als Sidecar-Container aus, der ein speichergestütztes emptyDir-Volume (medium: Memory) mit deinem Anwendungscontainer teilt, damit das Bearer-SVID niemals auf der Festplatte des Knotens landet. Mounte den SPIRE-Agent-Socket vom Host in den Sidecar, mounte das gemeinsame Volume unter /var/run/secrets/anthropic.com in beiden Containern und setze ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token im Anwendungscontainer. Auf VMs und Bare Metal führst du spiffe-helper als Systemdienst neben dem Workload aus und lässt beide auf ein gemeinsames Verzeichnis zeigen.



Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle Custom OIDC. 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: Registriere die öffentliche URL des OIDC Discovery Providers im discovery-Modus. Anthropic ruft /.well-known/openid-configuration von dieser URL ab und folgt der zurückgegebenen jwks_uri, um die Signaturschlüssel der Trust-Domain abzurufen.

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

Wenn der Discovery Provider nicht aus dem öffentlichen Internet erreichbar ist, rufe das JWKS selbst ab (curl https://oidc-discovery.prod.example.com/keys) und registriere den Issuer mit "jwks": {"type": "inline", "keys": [...]} unter Verwendung des Inhalts des zurückgegebenen keys-Arrays. Im inline-Modus wird die issuer_url nur mit dem iss-Claim des JWT-SVID verglichen. Anthropic versucht niemals, sie zu erreichen.

Um JWKS-Aktualisierungen zu automatisieren, ohne einen öffentlichen Discovery-Endpunkt bereitzustellen, konfiguriere ein SPIRE-Server-BundlePublisher-Plugin (aws_s3, gcp_cloudstorage oder k8s_configmap) mit format = "jwks", um die JWT-Signaturschlüssel bei jeder Rotation in einen externen Speicher zu übertragen, und aktualisiere dann die Inline-Schlüssel des Issuers über die Admin API.

Federation Rule: Gleiche den sub des JWT-SVID (die SPIFFE-ID) und die aud ab, die du spiffe-helper zum Anfordern konfiguriert hast. SPIFFE-IDs sind URI-Strings und subject_prefix gleicht sie als opaken Text ab, sodass sowohl ein exakter Wert als auch ein Präfix-Match mit abschließendem * funktionieren. Für komplexere Muster verwende eine CEL-condition.

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/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
}

token_lifetime_seconds ist die Lebensdauer des Anthropic-Access-Tokens, das der Exchange zurückgibt, nicht die des JWT-SVID. Das SDK aktualisiert das Access-Token automatisch.

Sei so spezifisch, wie es der Workload erlaubt. Lockere subject_prefix nur dann auf spiffe://prod.example.com/ns/inference/*, wenn jeder unter diesem Pfad registrierte Workload demselben Anthropic-Service-Account zugeordnet werden soll. Füge die fdrl_...-ID der Regel der Umgebungsvariable ANTHROPIC_FEDERATION_RULE_ID des Workloads hinzu.



Token beziehen und verwenden

Die Anthropic-SDKs können entweder das JWT-SVID aus der Datei lesen, die spiffe-helper pflegt, oder die SPIFFE Workload API direkt über ein Token-Provider-Callable aufrufen. Der Dateipfad ist die einfachste Integration und funktioniert in jeder SDK-Sprache. Der Callable-Pfad macht den Sidecar überflüssig, erfordert aber einen SPIFFE-Workload-API-Client in der Sprache deiner Anwendung.

import anthropic

# Liest die JWT-SVID, die spiffe-helper in
# ANTHROPIC_IDENTITY_TOKEN_FILE schreibt, sowie ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID und ANTHROPIC_WORKSPACE_ID.
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

Bevor du das SDK einbindest, rufe ein JWT-SVID direkt vom SPIRE Agent ab und bestätige, dass die Claims dem entsprechen, was deine Federation Rule erwartet. Wenn du eine andere SPIFFE-Implementierung verwendest, rufe ein JWT-SVID mit deren CLI oder Workload-API-Client ab und dekodiere die Payload auf die gleiche Weise.

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

Das Flag -output json gibt die SVID-Antwort und die Bundle-Antwort als zweielementiges JSON-Array zurück, sodass jq -r '.[0].svids[0].svid' das reine Token extrahiert. Auf älteren SPIRE-Versionen ohne -output gibt der Befehl stattdessen einen beschrifteten Block aus. Leite in diesem Fall die Standardausgabe durch awk '/^[[:space:]]*eyJ/{print $1; exit}', um die Token-Zeile zu extrahieren. Prüfe, dass iss die von dir registrierte OIDC-Discovery-Provider-URL ist, sub die SPIFFE-ID des Workloads ist und aud https://api.anthropic.com enthält. Führe dann das cURL-Beispiel aus Token beziehen und verwenden aus. Ein erfolgreicher Exchange gibt ein access_token zurück, das mit sk-ant-oat01- beginnt. Bei 400 invalid_grant siehe Fehlgeschlagenen Exchange beheben. Die häufigste SPIRE-seitige Ursache ist eine Diskrepanz zwischen dem jwt_issuer von SPIRE Server und der als Federation Issuer registrierten URL.



Regel eingrenzen

SPIFFE-ID-Pfadkonventionen werden vom Betreiber definiert, daher sollte der subject_prefix-Matcher der Federation Rule das Pfadschema widerspiegeln, das deine Registrierungseinträge verwenden. Gängige Schemata sind spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (der Standard, der von der ClusterSPIFFEID-Ressource in spire-controller-manager ausgegeben wird) und spiffe://<trust-domain>/host/<hostname>/<service> für VM- und Bare-Metal-Workloads.

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

• Auf einen Workload festlegen: Setze subject_prefix auf die vollständige SPIFFE-ID ohne abschließendes *.
• Immer eine Audience setzen: Verlange audience in der Regel und konfiguriere spiffe-helper (oder den Workload-API-Aufruf) mit demselben Wert, damit SVIDs, die für andere Relying Parties ausgestellt wurden, abgelehnt werden.
• Nach Pfadsegment eingrenzen: Verwende spiffe://prod.example.com/ns/inference/*, um jedem unter einem Namespace registrierten Workload Zugriff zu gewähren, und erstelle eine separate Regel und einen separaten Anthropic-Service-Account pro Namespace, anstatt eine einzelne Regel zu erweitern.
• Ein Issuer pro Trust-Domain: Jede SPIRE-Trust-Domain hat ihre eigenen Signaturschlüssel und ihren eigenen OIDC Discovery Provider. Registriere jede als separaten Federation Issuer und binde Regeln an den Issuer, dem die SPIFFE-IDs gehören, auf die sie passen.



Nächste Schritte