Utilizzare WIF con SPIFFE

SPIFFE è lo standard CNCF per l'emissione di identità ai workload. SPIRE è la sua implementazione di riferimento open source, e diversi prodotti commerciali emettono anch'essi identità conformi a SPIFFE. Anthropic si federa con qualsiasi implementazione SPIFFE che emetta JWT-SVID compatibili con OIDC. La federazione funziona tramite un documento di discovery OIDC a un URL HTTPS pubblico (modalità discovery; consulta i vincoli sugli URL) oppure registrando direttamente il JWKS (modalità inline). La specifica JWT-SVID definisce sub come lo SPIFFE ID del workload, e la SPIFFE Workload API richiede che il chiamante fornisca aud al momento del recupero, quindi questi claim sono identici tra le varie implementazioni. Anthropic richiede inoltre iss e iat, nessuno dei quali è obbligatorio secondo la specifica JWT-SVID, quindi configura la tua implementazione per popolare entrambi (in SPIRE, iss corrisponde all'impostazione server jwt_issuer e iat viene impostato automaticamente). Con questi elementi configurati, le sezioni Configurare Anthropic, Acquisire e utilizzare il token e Definire l'ambito della regola di questa guida si applicano a qualsiasi implementazione SPIFFE. Per un elenco aggiornato, consulta Commercial software that implements SPIFFE sul sito del progetto SPIFFE.

SPIFFE assegna a ogni workload un URI di identità stabile nella forma spiffe://<trust-domain>/<path>, e SPIRE emette tale identità come JWT-SVID su richiesta tramite la Workload API. Un JWT-SVID è un normale JWT firmato il cui claim sub è lo SPIFFE ID del workload e il cui claim aud viene fornito dal workload al momento del recupero.

Il ponte tra un trust domain SPIRE e lo standard OIDC è lo SPIRE OIDC Discovery Provider, un helper autonomo che pubblica /.well-known/openid-configuration e un endpoint JWKS per le chiavi di firma JWT del trust domain. Con il discovery provider in esecuzione, un JWT-SVID viene validato come qualsiasi altro token OIDC: registra l'URL di discovery come federation issuer, scrivi una federation rule che corrisponda allo SPIFFE ID del workload e fai in modo che il workload presenti il proprio JWT-SVID all'endpoint di token exchange di Anthropic.

Gli esempi in questa pagina utilizzano SPIRE e si applicano ovunque sia in esecuzione SPIRE Agent: pod Kubernetes, macchine virtuali e host bare-metal.

Prerequisiti

• Familiarità con i concetti di WIF: service account, federation issuer e federation rule.
• Un deployment SPIFFE con identità di workload emesse (gli esempi in questa pagina utilizzano SPIRE Server e Agent) e registration entry per i workload che devono chiamare l'API di Claude.
• Un endpoint di discovery OIDC per il trust domain (in SPIRE, l'OIDC Discovery Provider) in esecuzione con un endpoint HTTPS raggiungibile pubblicamente, oppure il JWKS esportato per la registrazione inline.
• Il tuo issuer SPIFFE configurato per impostare il claim iss sui JWT-SVID al valore che registrerai come issuer_url del federation issuer. Per la modalità discovery, questo è l'URL pubblico dell'endpoint di discovery (in SPIRE, l'impostazione server jwt_issuer).
• JWT-SVID disponibili per i tuoi workload. WIF accetta solo JWT-SVID; gli X.509-SVID non vengono utilizzati.
• Autorizzazione a creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.

Il valore di audience da richiedere quando si recupera un JWT-SVID è sempre https://api.anthropic.com. Usa questo valore in jwt_audience di spiffe-helper, nella chiamata FetchJWTSVID della Workload API e nel matcher audience della federation rule.

Configurare SPIRE

Le istruzioni in questa sezione sono specifiche per SPIRE. Se utilizzi un issuer SPIFFE diverso, configura il suo endpoint di discovery OIDC e il recupero dei JWT-SVID secondo la sua documentazione, quindi prosegui con Configurare Anthropic.

Se esegui già SPIRE con l'OIDC Discovery Provider, la federazione con Anthropic richiede tre elementi lato SPIRE: un jwt_issuer che corrisponda all'URL di discovery, una registration entry per il workload che chiamerà l'API di Claude e un modo per quel workload di recuperare un JWT-SVID con l'audience di Anthropic. Le sottosezioni seguenti illustrano ciascuno di questi elementi. Gli snippet di configurazione mostrano solo le impostazioni rilevanti per la federazione con Anthropic; non sono configurazioni complete di deployment SPIRE.

Verificare il JWT issuer

Anthropic valida un JWT-SVID confrontando il suo claim iss con un federation issuer registrato e recuperando il JWKS dal documento di discovery di quell'issuer. Due impostazioni SPIRE devono concordare sullo stesso URL: jwt_issuer di SPIRE Server (che diventa il claim iss in ogni JWT-SVID emesso) e l'elenco domains dell'OIDC Discovery Provider (che determina l'host da cui vengono serviti il documento di discovery e il JWKS). Quell'URL condiviso è ciò che registri presso Anthropic.

Il trust domain e l'URL dell'issuer sono indipendenti. Il trust domain (spiffe://prod.example.com) definisce l'ambito del claim sub; l'URL dell'issuer (https://oidc-discovery.prod.example.com) è dove Anthropic recupera le chiavi di firma. Non è necessario che condividano un hostname.

Verifica che jwt_issuer sia impostato nella configurazione di SPIRE Server e punti all'URL pubblico del discovery provider. L'esempio seguente mostra anche una durata predefinita per i JWT-SVID; il valore predefinito integrato di SPIRE è 5 minuti, abbastanza breve da richiedere una rotazione continua (consulta Eseguire spiffe-helper). L'endpoint di token exchange di Anthropic rifiuta qualsiasi identity token la cui durata superi il massimo configurato per il federation issuer (1 ora per impostazione predefinita; consulta Regole di validazione). Questo controllo si applica a ogni implementazione SPIFFE, non solo a SPIRE, quindi mantieni default_jwt_svid_ttl (o qualsiasi override per singola entry) pari o inferiore a quel massimo.

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

Nella configurazione dell'OIDC Discovery Provider, lo stesso hostname deve apparire sotto domains, e il provider deve essere in grado di raggiungere il socket API di SPIRE Server. Il provider serve il documento di discovery e il JWKS tramite HTTPS; termina TLS con il suo supporto ACME integrato oppure anteponi un load balancer che lo faccia.

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

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

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

Registrare il workload

Ogni workload che chiama l'API di Claude necessita di una registration entry SPIRE che mappi i suoi selettori di runtime a uno SPIFFE ID. Se il workload è già registrato, annota il suo SPIFFE ID; lo utilizzerai nel subject_prefix della federation rule. In caso contrario, registralo. Per un pod Kubernetes, i selettori sono tipicamente il namespace e il service account Kubernetes:

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

I workload al di fuori di Kubernetes utilizzano selettori a livello di host come unix:uid:1000 (unix:path è anch'esso disponibile ma richiede discover_workload_path = true nella configurazione dell'attestatore di workload unix dell'agent). I cluster che eseguono spire-controller-manager possono dichiarare le entry con la custom resource ClusterSPIFFEID invece di chiamare direttamente spire-server entry create.

Eseguire spiffe-helper

spiffe-helper è un'utility sidecar che si connette al socket di SPIRE Agent, recupera un JWT-SVID per una determinata audience, lo scrive su un file e lo recupera nuovamente prima della scadenza. L'helper viene eseguito in modalità daemon per impostazione predefinita; l'esempio seguente imposta esplicitamente daemon_mode = true.

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, esegui spiffe-helper come container sidecar che condivide un volume emptyDir in memoria (medium: Memory) con il container dell'applicazione, in modo che lo SVID bearer non venga mai scritto sul disco del nodo. Monta il socket di SPIRE Agent dall'host nel sidecar, monta il volume condiviso in /var/run/secrets/anthropic.com in entrambi i container e imposta ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token sul container dell'applicazione. Su VM e bare metal, esegui spiffe-helper come servizio di sistema accanto al workload e fai puntare entrambi a una directory condivisa.

Configurare Anthropic

Segui la procedura di configurazione per registrare un federation issuer, creare un service account Anthropic e creare una federation rule nella Claude Console. Utilizza questi valori specifici per SPIFFE.

Federation issuer: Registra l'URL pubblico dell'OIDC Discovery Provider in modalità discovery. Anthropic recupera /.well-known/openid-configuration da questo URL e segue il jwks_uri restituito per recuperare le chiavi di firma del trust domain.

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

Se il discovery provider non è raggiungibile da internet pubblico, recupera tu stesso il JWKS (curl https://oidc-discovery.prod.example.com/keys) e registra l'issuer con "jwks": {"type": "inline", "keys": [...]} utilizzando il contenuto dell'array keys restituito. In modalità inline l'issuer_url viene solo confrontato con il claim iss del JWT-SVID; Anthropic non tenta mai di raggiungerlo.

Per automatizzare gli aggiornamenti del JWKS senza esporre un endpoint di discovery pubblico, configura un plugin BundlePublisher di SPIRE Server (aws_s3, gcp_cloudstorage o k8s_configmap) con format = "jwks" per inviare le chiavi di firma JWT a uno storage esterno a ogni rotazione, quindi sincronizzalo nelle chiavi inline dell'issuer.

Federation rule: Fai corrispondere il sub del JWT-SVID (lo SPIFFE ID) e l'aud che hai configurato spiffe-helper a richiedere. Gli SPIFFE ID sono stringhe URI e subject_prefix li confronta come testo opaco, quindi sia un valore esatto sia una corrispondenza di prefisso con * finale funzionano su di essi. Per pattern più complessi, utilizza una condition CEL.

{
  "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
}

Sii il più specifico possibile in base al workload. Allenta subject_prefix a spiffe://prod.example.com/ns/inference/* solo se ogni workload registrato sotto quel percorso deve essere mappato allo stesso service account Anthropic. Aggiungi l'ID fdrl_... della regola alla variabile d'ambiente ANTHROPIC_FEDERATION_RULE_ID del workload.

Acquisire e utilizzare il token

Gli SDK Anthropic possono leggere il JWT-SVID dal file che spiffe-helper mantiene oppure chiamare direttamente la SPIFFE Workload API tramite un callable token-provider. Il percorso basato su file è l'integrazione più semplice e funziona in ogni linguaggio SDK; il percorso basato su callable elimina il sidecar ma richiede un client SPIFFE Workload API nel linguaggio della tua applicazione.

Verificare la configurazione

Prima di integrare l'SDK, recupera un JWT-SVID direttamente da SPIRE Agent e verifica che i claim corrispondano a ciò che la tua federation rule si aspetta. Se utilizzi un'implementazione SPIFFE diversa, recupera un JWT-SVID con la sua CLI o il suo client Workload API e decodifica il payload allo stesso modo.

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'

Il flag -output json restituisce la risposta SVID e la risposta bundle come un array JSON di due elementi, quindi jq -r '.[0].svids[0].svid' estrae il token puro. Nelle versioni SPIRE più vecchie senza -output, il comando stampa invece un blocco etichettato; in tal caso invia l'output predefinito in pipe a awk '/^[[:space:]]*eyJ/{print $1; exit}' per estrarre la riga del token. Verifica che iss sia l'URL dell'OIDC Discovery Provider che hai registrato, che sub sia lo SPIFFE ID del workload e che aud contenga https://api.anthropic.com. Quindi esegui l'esempio cURL da Acquisire e utilizzare il token; uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01-. In caso di 400 invalid_grant, consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato SPIRE è una discrepanza tra jwt_issuer di SPIRE Server e l'URL registrato come federation issuer.

Definire l'ambito della regola

Le convenzioni di percorso degli SPIFFE ID sono definite dall'operatore, quindi il matcher subject_prefix della federation rule dovrebbe riflettere lo schema di percorso utilizzato dalle tue registration entry. Gli schemi comuni includono spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (il valore predefinito emesso dalla risorsa ClusterSPIFFEID in spire-controller-manager) e spiffe://<trust-domain>/host/<hostname>/<service> per workload su VM e bare-metal.

Limita il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

• Vincola a un singolo workload: Imposta subject_prefix allo SPIFFE ID completo senza * finale.
• Imposta sempre un'audience: Richiedi audience sulla regola e configura spiffe-helper (o la chiamata Workload API) con lo stesso valore in modo che gli SVID emessi per altre relying party vengano rifiutati.
• Definisci l'ambito per segmento di percorso: Usa spiffe://prod.example.com/ns/inference/* per concedere l'accesso a ogni workload registrato sotto un namespace, e crea una regola e un service account Anthropic separati per ogni namespace invece di ampliare una singola regola.
• Un issuer per trust domain: Ogni trust domain SPIRE ha le proprie chiavi di firma e il proprio OIDC Discovery Provider. Registra ciascuno come federation issuer separato e associa le regole all'issuer che possiede gli SPIFFE ID a cui corrispondono.

Passaggi successivi

• Workload Identity Federation: concetti, il flusso di token exchange e opzioni di configurazione dell'SDK.
• Riferimento WIF: variabili d'ambiente, modalità di origine JWKS e modalità di match delle regole.
• Utilizzare WIF con Kubernetes: per cluster che utilizzano token nativi di service account proiettati invece di SPIRE.