Usare 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. Per un elenco aggiornato delle implementazioni, consulta Commercial software that implements SPIFFE sul sito del progetto SPIFFE.

La federazione funziona tramite un documento di discovery OIDC a un URL HTTPS pubblico (modalità discovery, soggetta ai 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 fetch, quindi questi claim sono gli stessi in tutte le implementazioni. Anthropic richiede inoltre iss e iat, nessuno dei quali è imposto dalla specifica JWT-SVID, quindi configura la tua implementazione in modo che popoli entrambi (in SPIRE, iss è l'impostazione server jwt_issuer e iat viene impostato automaticamente). Con questi elementi configurati, le sezioni Configurare Anthropic, Acquisire e usare il token e Delimitare l'ambito della regola di questa guida si applicano a qualsiasi implementazione 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 fetch.

Il ponte tra un trust domain SPIRE e l'OIDC standard è 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 (issuer di federazione), scrivi una federation rule (regola di federazione) 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 di questa pagina usano 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à dei workload emesse (gli esempi di questa pagina usano SPIRE Server e Agent), e registration entry per i workload che devono chiamare la Claude API.
• 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, non X.509-SVID.
• Permesso di 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 di questa sezione sono specifiche per SPIRE. Se usi un issuer SPIFFE diverso, configura il suo endpoint di discovery OIDC e il recupero dei JWT-SVID secondo la sua documentazione, quindi prosegui da Configurare Anthropic.

Se esegui già SPIRE con l'OIDC Discovery Provider, la federazione con Anthropic richiede tre cose lato SPIRE: un jwt_issuer che corrisponda all'URL di discovery, una registration entry per il workload che chiamerà la Claude API e un modo per quel workload di recuperare un JWT-SVID con l'audience Anthropic. Le sottosezioni seguenti illustrano ciascuna di esse. Gli snippet di configurazione mostrano solo le impostazioni rilevanti per la federazione con Anthropic, non 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 la lista 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'issuer URL sono indipendenti. Il trust domain (spiffe://prod.example.com) delimita l'ambito del claim sub. L'issuer URL (https://oidc-discovery.prod.example.com) è dove Anthropic recupera le chiavi di firma. Non è necessario che condividano un hostname.

Conferma 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 dei JWT-SVID. Il valore predefinito integrato di SPIRE è 5 minuti, abbastanza breve da richiedere una rotazione continua (vedi 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, che è 1 ora per impostazione predefinita (vedi 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 comparire sotto domains, e il provider deve poter 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 anteponigli un load balancer che lo faccia.

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

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

acme {
    email        = "platform@example.com"
    tos_accepted = true
}

Registrare il workload

Ogni workload che chiama la Claude API 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, che userai 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:

# Sostituisci NODE_UID con l'UID del nodo:
#   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

I workload al di fuori di Kubernetes usano selettori a livello di host come unix:uid:1000 (unix:path è anch'esso disponibile ma richiede discover_workload_path = true nella configurazione del workload attestor 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 in un file e lo recupera nuovamente prima della scadenza. L'helper viene eseguito in modalità daemon per impostazione predefinita. L'esempio seguente imposta daemon_mode = true esplicitamente.

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, esegui spiffe-helper come container sidecar che condivide un volume emptyDir in memoria (medium: Memory) con il container della tua applicazione, in modo che lo SVID bearer non finisca mai 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

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona Custom OIDC. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un service account e nella creazione di una federation rule.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

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 ottenere 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 dalla rete internet pubblica, recupera tu stesso il JWKS (curl https://oidc-discovery.prod.example.com/keys) e registra l'issuer con "jwks": {"type": "inline", "keys": [...]} usando 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 aggiorna le chiavi inline dell'issuer tramite l'Admin API.

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 per prefisso con * finale funzionano con essi. Per pattern più complessi, usa 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
}

token_lifetime_seconds è la durata dell'access token Anthropic restituito dallo scambio, non del JWT-SVID. L'SDK aggiorna l'access token automaticamente.

Sii specifico quanto il workload consente. 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 usare il token

Gli SDK Anthropic possono leggere il JWT-SVID dal file mantenuto da spiffe-helper 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 degli SDK. Il percorso basato su callable elimina il sidecar ma richiede un client SPIFFE Workload API nel linguaggio della tua applicazione.

import anthropic

# Legge il JWT-SVID che spiffe-helper scrive in
# ANTHROPIC_IDENTITY_TOKEN_FILE, oltre a ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e 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"))

Verificare la configurazione

Prima di integrare l'SDK, recupera un JWT-SVID direttamente da SPIRE Agent e conferma che i claim corrispondano a quanto si aspetta la tua federation rule. Se usi 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 array JSON di due elementi, quindi jq -r '.[0].svids[0].svid' estrae il token nudo. Nelle versioni più vecchie di SPIRE senza -output, il comando stampa invece un blocco etichettato. In quel caso, passa l'output predefinito attraverso awk '/^[[:space:]]*eyJ/{print $1; exit}' per estrarre la riga del token. Controlla 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 usare il token. Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01-. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto e 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.

Delimitare l'ambito della regola

Le convenzioni sui percorsi degli SPIFFE ID sono definite dall'operatore, quindi il matcher subject_prefix della federation rule dovrebbe riflettere lo schema di percorsi usato dalle tue registration entry. 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.

Vincola 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 nella regola e configura spiffe-helper (o la chiamata alla Workload API) con lo stesso valore, in modo che gli SVID emessi per altre relying party vengano rifiutati.
• Delimita per segmento di percorso: Usa spiffe://prod.example.com/ns/inference/* per autorizzare 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