WIF mit SPIFFE verwenden

SPIFFE ist der CNCF-Standard für die Ausstellung von Identitäten an Workloads. SPIRE ist die 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. Die Föderation funktioniert entweder über ein OIDC-Discovery-Dokument unter einer öffentlichen HTTPS-URL (discovery-Modus; siehe die 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 beim Abruf 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 sind; konfiguriere deine Implementierung also so, dass beide gesetzt werden (in SPIRE ist iss die Server-Einstellung jwt_issuer, und iat wird automatisch gesetzt). Wenn das erledigt ist, gelten die Abschnitte Anthropic konfigurieren, Token abrufen und verwenden und Regel eingrenzen dieses Leitfadens für jede SPIFFE-Implementierung. Eine aktuelle Liste findest du unter Commercial software that implements SPIFFE auf der SPIFFE-Projektseite.

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 beim Abruf 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. Wenn der Discovery Provider läuft, validiert ein JWT-SVID wie jedes andere OIDC-Token: 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 an Anthropics Token-Exchange-Endpunkt übergeben.

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 WIF-Konzepten: Service Accounts, Federation Issuers und Federation Rules.
• Eine SPIFFE-Bereitstellung 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 exportierte JWKS für die inline-Registrierung.
• Dein SPIFFE-Issuer ist so konfiguriert, dass der iss-Claim in JWT-SVIDs auf den Wert gesetzt wird, den du als issuer_url des Federation Issuers registrierst. Im discovery-Modus ist dies die öffentliche URL des Discovery-Endpunkts (in SPIRE die Server-Einstellung jwt_issuer).
• JWT-SVIDs, die deinen Workloads zur Verfügung stehen. WIF akzeptiert nur JWT-SVIDs; X.509-SVIDs werden nicht verwendet.
• 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 JWT-SVID-Abruf gemäß der jeweiligen 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 aufruft, 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; es sind 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 Signaturschlüssel abruft. Sie müssen keinen gemeinsamen Hostnamen haben.

Vergewissere dich, 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). Anthropics Token-Exchange-Endpunkt lehnt jedes Identity-Token ab, dessen Lebensdauer das konfigurierte Maximum des Federation Issuers überschreitet (standardmäßig 1 Stunde; siehe Validierungsregeln). Diese Prüfung gilt für jede SPIFFE-Implementierung, nicht nur für SPIRE; halte also 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 integrierten ACME-Unterstützung oder schalte einen Load Balancer davor, der das ü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 seine SPIFFE-ID; du verwendest sie im subject_prefix der Federation Rule. Falls nicht, registriere ihn. Für einen Kubernetes-Pod sind die Selektoren typischerweise der Namespace und der Kubernetes-Service-Account:

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-Dienstprogramm, 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"
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 auf dem Anwendungscontainer. Auf VMs und Bare Metal führst du spiffe-helper als Systemdienst neben dem Workload aus und richtest beide auf ein gemeinsames Verzeichnis aus.

Anthropic konfigurieren

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

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-Updates 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 pushen, und synchronisiere diesen dann in die Inline-Keys des Issuers.

Federation Rule: Matche das sub des JWT-SVID (die SPIFFE-ID) und das aud, das du spiffe-helper zum Anfordern konfiguriert hast. SPIFFE-IDs sind URI-Strings, und subject_prefix matcht sie als opaken Text, 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
}

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 zur Umgebungsvariable ANTHROPIC_FEDERATION_RULE_ID des Workloads hinzu.

Token abrufen 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.

Einrichtung ü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 den 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. Bei ä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. Überprüfe, dass iss die URL des OIDC Discovery Providers ist, die du registriert hast, 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. Bei 400 invalid_grant siehe Fehlgeschlagenen Austausch beheben; die häufigste Ursache auf SPIRE-Seite ist eine Diskrepanz zwischen 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 Bereich, 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 pro Namespace eine separate Regel und einen separaten Anthropic-Service-Account, anstatt eine 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 matchen.

Nächste Schritte

• Workload Identity Federation: Konzepte, der Token-Exchange-Ablauf und SDK-Konfigurationsoptionen.
• WIF-Referenz: Umgebungsvariablen, JWKS-Quellmodi und Regel-Match-Modi.
• WIF mit Kubernetes verwenden: für Cluster, die native projizierte Service-Account-Tokens anstelle von SPIRE verwenden.