WIF mit SPIFFE verwenden

SPIFFE ist der CNCF-Standard für die Ausstellung von Identitäten an Workloads. SPIRE ist dessen 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, unterliegt den URL-Einschränkungen) oder durch 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 Abrufzeitpunkt angibt, sodass diese Claims über alle Implementierungen hinweg gleich sind. Anthropic verlangt zusätzlich iss und iat, die beide von der JWT-SVID-Spezifikation nicht vorgeschrieben werden. Konfiguriere deine Implementierung daher so, dass sie beide befüllt (in SPIRE ist iss die Server-Einstellung jwt_issuer, und iat wird automatisch gesetzt). Sobald diese vorhanden sind, gelten die Abschnitte Anthropic konfigurieren, Token abrufen und verwenden und Deine 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 über die Workload API als JWT-SVID 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 Abrufzeitpunkt angegeben wird.

Die Brücke von einer SPIRE-Trust-Domain zu Standard-OIDC ist der SPIRE OIDC Discovery Provider, ein eigenständiges Hilfsprogramm, das /.well-known/openid-configuration und einen JWKS-Endpunkt für die JWT-Signaturschlüssel der Trust-Domain veröffentlicht. Wenn der Discovery Provider läuft, 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 lass den Workload sein JWT-SVID am Token-Exchange-Endpunkt von Anthropic vorlegen.

Die Beispiele auf dieser Seite verwenden SPIRE und gelten überall, 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-Issuer ist so konfiguriert, dass er den iss-Claim in JWT-SVIDs auf den Wert setzt, 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 stehen deinen Workloads zur Verfügung. WIF akzeptiert nur 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 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-Issuer verwendest, konfiguriere dessen OIDC-Discovery-Endpunkt und den JWT-SVID-Abruf gemäß seiner eigenen Dokumentation und fahre dann bei Anthropic konfigurieren fort.

Wenn du SPIRE bereits mit dem OIDC Discovery Provider betreibst, erfordert die Föderation mit Anthropic auf SPIRE-Seite drei Dinge: 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 dieser Punkte. Die Konfigurationsausschnitte zeigen nur die für die Anthropic-Föderation relevanten Einstellungen, keine vollständigen SPIRE-Deployment-Konfigurationen.

Den 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 (wird zum iss-Claim in jedem ausgestellten JWT-SVID) und die domains-Liste des OIDC Discovery Providers (bestimmt den Host, 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 voneinander unabhängig. Die Trust-Domain (spiffe://prod.example.com) grenzt den sub-Claim ein. 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.

Stelle sicher, dass jwt_issuer in der Konfiguration von SPIRE Server gesetzt ist und auf die öffentliche URL des Discovery Providers zeigt. Das folgende Beispiel zeigt außerdem 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 Identitätstoken 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 eintragsspezifische Überschreibung) 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 schalte 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        = "platform@example.com"
    tos_accepted = true
}

Den 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 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 Selektoren auf Host-Ebene 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-Hilfsprogramm, 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"
}]

Führe spiffe-helper in Kubernetes als Sidecar-Container aus, der ein speichergestütztes emptyDir-Volume (medium: Memory) mit deinem Anwendungscontainer teilt, sodass das Bearer-SVID niemals auf der Festplatte des Knotens landet. Mounte den SPIRE-Agent-Socket vom Host in den Sidecar, mounte das gemeinsame Volume in beiden Containern unter /var/run/secrets/anthropic.com und setze ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token im Anwendungscontainer. Auf VMs und Bare Metal führe spiffe-helper als Systemdienst neben dem Workload aus und lass 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, das Erstellen eines Service Accounts und das Erstellen 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 BundlePublisher-Plugin von SPIRE Server (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 anfordern lässt. 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 Austausch zurückgibt, nicht die des JWT-SVID. Das SDK erneuert das Access-Token automatisch.

Sei so spezifisch, wie der Workload es zulässt. 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 zur Umgebungsvariable ANTHROPIC_FEDERATION_RULE_ID des Workloads hinzu.

Token abrufen und verwenden

Die Anthropic SDKs können das JWT-SVID entweder 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-Weg macht den Sidecar überflüssig, erfordert aber einen SPIFFE-Workload-API-Client in der Sprache deiner Anwendung.

import anthropic

# Liest das JWT-SVID, das spiffe-helper nach
# 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"))

Das Setup überprüfen

Bevor du das SDK einbindest, rufe ein JWT-SVID direkt von 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 dieselbe 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 URL des OIDC Discovery Providers ist, sub die SPIFFE-ID des Workloads ist und aud https://api.anthropic.com enthält. Führe dann das cURL-Beispiel aus Token abrufen und verwenden aus. Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt. Wenn der Austausch mit der opaken 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 SPIRE-Seite ist eine Abweichung zwischen jwt_issuer von SPIRE Server und der als Federation Issuer registrierten URL.

Deine Regel eingrenzen

Die Pfadkonventionen für SPIFFE-IDs werden vom Betreiber festgelegt, 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, den die ClusterSPIFFEID-Ressource in spire-controller-manager ausgibt) und spiffe://<trust-domain>/host/<hostname>/<service> für VM- und Bare-Metal-Workloads.

Beschränke den match-Block der Regel auf den engsten Geltungsbereich, 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, sodass für andere Relying Parties ausgestellte SVIDs 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 pro Namespace eine separate Regel und einen separaten Anthropic-Service-Account, anstatt eine Regel auszuweiten.
• 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