Usa 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 federa con qualsiasi implementazione SPIFFE che emette 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 recupero, quindi questi claim sono gli stessi in tutte le implementazioni. Anthropic richiede inoltre iss e iat, nessuno dei quali è obbligatorio secondo la specifica JWT-SVID, quindi configura la tua implementazione per popolarli entrambi (in SPIRE, iss è l'impostazione del server jwt_issuer e iat viene impostato automaticamente). Con questi in atto, le sezioni Configura Anthropic, Acquisisci e usa il token e Delimita la tua 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 quell'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 è fornito dal workload al momento del recupero.

Il ponte da un trust domain SPIRE allo 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 convalidato 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 suo JWT-SVID all'endpoint di token-exchange di Anthropic.

Gli esempi di questa pagina usano SPIRE e si applicano ovunque SPIRE Agent sia in esecuzione: 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 emittente 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 del server jwt_issuer).
• JWT-SVID disponibili per i tuoi workload. WIF accetta solo JWT-SVID, non X.509-SVID.
• 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 nel jwt_audience di spiffe-helper, nella chiamata FetchJWTSVID della Workload API e nel matcher audience della federation rule.



Configura SPIRE

Le istruzioni in questa sezione sono specifiche per SPIRE. Se usi un emittente SPIFFE diverso, configura il suo endpoint di discovery OIDC e il recupero dei JWT-SVID secondo la sua documentazione, poi prosegui da Configura Anthropic.

Se esegui già SPIRE con l'OIDC Discovery Provider, la federazione con Anthropic richiede tre cose sul 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 di Anthropic. Le sottosezioni seguenti illustrano ciascuno di questi punti. I frammenti di configurazione mostrano solo le impostazioni rilevanti per la federazione con Anthropic, non configurazioni complete di deployment SPIRE.



Verifica l'emittente JWT

Anthropic convalida un JWT-SVID confrontando il suo claim iss con un federation issuer registrato e recuperando il JWKS dal documento di discovery di quell'emittente. Due impostazioni di SPIRE devono concordare sullo stesso URL: il 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'emittente sono indipendenti. Il trust domain (spiffe://prod.example.com) delimita il claim sub. L'URL dell'emittente (https://oidc-discovery.prod.example.com) è il luogo da cui 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 del JWT-SVID. Il valore predefinito integrato di SPIRE è 5 minuti, abbastanza breve da richiedere una rotazione continua (vedi Esegui 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 convalida). 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 essere in grado di raggiungere il socket API di SPIRE Server. Il provider serve il documento di discovery e il JWKS tramite HTTPS. Termina il TLS con il suo supporto ACME integrato, oppure mettilo dietro 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
}



Registra il workload

Ogni workload che chiama la Claude API ha bisogno 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 dell'unix workload attestor 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.



Esegui 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 basato su memoria (medium: Memory) con il container della tua applicazione, in modo che il bearer SVID 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.



Configura 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 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 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 confrontato solo 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, poi 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 di 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 automaticamente l'access token.

Sii il più specifico possibile per quanto consentito dal 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.



Acquisisci e usa il token

Gli SDK di 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 dell'SDK. Il percorso con 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"))



Verifica la configurazione

Prima di collegare l'SDK, recupera un JWT-SVID direttamente da SPIRE Agent e conferma che i claim corrispondano a ciò che la tua federation rule si aspetta. Se usi un'implementazione SPIFFE diversa, recupera un JWT-SVID con la sua CLI o il suo client Workload API e decodifica il payload nello 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 a due elementi, quindi jq -r '.[0].svids[0].svid' estrae il token puro. 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. 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. Poi esegui l'esempio cURL da Acquisisci e usa 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 il jwt_issuer di SPIRE Server e l'URL registrato come federation issuer.



Delimita la tua regola

Le convenzioni dei 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. 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 i workload su VM e bare-metal.

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

• Vincola a un singolo workload: Imposta subject_prefix sullo 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 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.



Prossimi passi