Workload Identity Federation

La "Workload Identity Federation" (federazione delle identità dei workload), o WIF, consente ai tuoi workload di autenticarsi verso la Claude API con token OpenID Connect (OIDC) a breve durata invece di chiavi API sk-ant-... a lunga durata. I token provengono da un "identity provider" (provider di identità), o IdP, che già gestisci: AWS IAM, Google Cloud o qualsiasi emittente OIDC conforme agli standard come GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID o Okta.

Il tuo workload presenta un JWT firmato dal tuo identity provider. Anthropic lo convalida rispetto alle regole di fiducia che configuri nella Claude Console e restituisce un token di accesso Anthropic a breve durata associato a un service account nella tua organizzazione. Non ci sono segreti statici da generare, archiviare nella CI, ruotare o far trapelare.

La Workload Identity Federation rafforza la tua postura di sicurezza sostituendo le chiavi API statiche con token che scadono in pochi minuti anziché mai. Non costituisce da sola una soluzione di sicurezza completa: l'autenticazione federata è forte solo quanto l'identity provider a monte che firma il JWT. Abbina la Workload Identity Federation ai controlli che il tuo IdP già supporta (binding dell'identità del workload, accesso condizionale, audit logging) per una difesa in profondità.

Concetti

Configuri tre risorse nella Claude Console prima che qualsiasi workload possa federarsi. Insieme esprimono "i token firmati dall'emittente X, con claim che hanno l'aspetto di Y, possono agire come service account Z."

Service account

Un service account (account di servizio, svac_...) è un'identità non umana con nome all'interno della tua organizzazione Anthropic. È il principal per conto del quale agisce una chiave di service account o un token federato. I service account esistono a livello di organizzazione e diventano attivi in un workspace quando li aggiungi come membri di quel workspace. Al momento dello scambio, Anthropic verifica che il workspace della regola di federazione corrisponda a una delle appartenenze ai workspace del service account; il token generato segue quindi i limiti di velocità e l'attribuzione dell'utilizzo di quel workspace, esattamente come una chiave API. A differenza di un utente umano, un service account non ha email, password né accesso alla Console. Ogni service account è implicitamente membro del workspace predefinito della tua organizzazione; aggiungi appartenenze esplicite per qualsiasi altro workspace in cui debba agire. Per consentire a una chiave di service account valida per tutti i workspace di agire in un workspace, aggiungi il service account a quel workspace.

La distinzione chiave rispetto a una chiave API di workspace: una chiave API di workspace è una credenziale, mentre un service account ha delle credenziali. Puoi verificare più facilmente quali workload hanno agito come quale service account.

Emittenti di federazione

Un federation issuer (emittente di federazione, fdis_...) registra un identity provider OIDC presso la tua organizzazione. Registrare un emittente comunica ad Anthropic "i JWT firmati da questo provider possono asserire l'identità dei workload per la mia organizzazione."

Un emittente ha due elementi di configurazione:

• URL dell'emittente: Il valore esatto del claim iss che appare nei JWT del provider, ad esempio https://token.actions.githubusercontent.com o https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Sorgente JWKS: Il modo in cui Anthropic recupera le chiavi pubbliche per verificare le firme dei JWT. Usa discovery (il valore predefinito) per qualsiasi provider che serve /.well-known/openid-configuration al proprio URL dell'emittente. Usa explicit_url per puntare direttamente a un endpoint JWKS, oppure inline per caricare il set di chiavi per emittenti non raggiungibili dalla rete internet pubblica (ad esempio, un cluster Kubernetes privato).

Gli URL dell'emittente e del JWKS devono essere https, sulla porta 443, e usare un hostname DNS pubblico che si risolva in indirizzi IP pubblici; gli IP letterali non sono accettati. Questi vincoli si applicano solo agli URL che Anthropic recupera; nelle modalità explicit_url e inline l'issuer_url viene confrontato come stringa e può fare riferimento a un hostname interno.

In genere registri un emittente per ambiente: il tuo cluster EKS di produzione, il tuo cluster di staging e GitHub Actions sono tre emittenti separati.

Regole di federazione

Una federation rule (regola di federazione, fdrl_...) è il ponte tra un emittente e un service account: "quando un JWT dall'emittente X ha claim che hanno l'aspetto di Y, genera un token per il service account Z con scope S."

Una regola definisce le condizioni di corrispondenza, un target, e lo scope di autorizzazione e la durata del token che si applicano quando la regola corrisponde:

• Corrispondenza: Le condizioni che un JWT in ingresso deve soddisfare. Puoi effettuare la corrispondenza su un subject_prefix (ad esempio, system:serviceaccount:prod:worker, oppure con un * finale per una corrispondenza di prefisso), un audience esatto, una mappa di valori esatti dei claim, un'espressione condition in CEL per logica complessa, o qualsiasi combinazione. Almeno uno tra subject_prefix, claims o condition deve essere impostato, e tutti i matcher configurati devono essere soddisfatti affinché il JWT venga accettato.
• Target: Il service account a cui viene mappato il JWT corrispondente.
• Autorizzazione: Lo scope OAuth concesso sul token generato. Il valore predefinito è workspace:developer, che concede lo stesso accesso di una chiave API di workspace. Alcuni prodotti bloccano lo scope quando crei una regola dal loro flusso; ad esempio, la finestra modale di creazione tunnel degli MCP tunnels crea regole con scope workspace:manage_tunnels. Consulta Scope OAuth. La regola imposta anche token_lifetime_seconds (da 60 a 86400, predefinito 3600).

Un singolo emittente può avere molte regole: una per team, namespace o livello di permesso. Le regole vengono valutate per ID: il client specifica quale regola usare nella richiesta di scambio, e Anthropic verifica che il JWT soddisfi i criteri di corrispondenza di quella regola. Non esiste una ricerca implicita delle regole.

Come funziona

1. Il tuo IdP emette un JWT per il workload. Sulla maggior parte delle piattaforme questo è ambientale: un token di service account proiettato di Kubernetes, il metadata server di Google Cloud, Azure IMDS o l'endpoint OIDC di GitHub Actions. Il claim iss del JWT identifica il provider, e il suo sub e gli altri claim identificano il workload specifico.
2. L'SDK scambia il JWT con un token di accesso Anthropic. L'SDK invia il JWT a POST /v1/oauth/token usando il grant jwt-bearer di RFC 7523. Anthropic verifica il JWT rispetto al JWKS dell'emittente e alle condizioni di corrispondenza della regola di federazione, quindi restituisce un token sk-ant-oat01-... a breve durata che agisce per conto del service account target della regola.
3. L'SDK invia il token a ogni richiesta e lo rinnova prima che scada. Il codice della tua applicazione costruisce il client senza api_key e chiama l'API come di consueto. L'SDK riesegue lo scambio prima che il token scada.

Configura la federazione

Ti servono il ruolo admin, owner o primary owner nella tua organizzazione Anthropic, un identity provider compatibile con OIDC con un endpoint JWKS raggiungibile (o un documento JWKS che puoi incollare, per cluster air-gapped), e un workload in grado di ottenere un token di identità da quel provider.

La procedura guidata Connect workload crea tutte e tre le risorse (l'emittente, il service account e la regola di federazione) in un unico flusso guidato, quindi verifica la connessione end-to-end.

1. 1

   Apri Connect workload

   Nella Claude Console, vai su Settings → Workload identity e seleziona Connect workload.

2. 2

   Scegli il tuo provider

   Seleziona il riquadro del tuo identity provider: GitHub Actions, AWS, Google Cloud, Microsoft Entra ID o Kubernetes. Ogni riquadro precompila il pattern dell'URL dell'emittente e i campi di corrispondenza supportati dai JWT di quel provider. Per qualsiasi altro provider conforme agli standard (come SPIFFE o Okta), seleziona Custom OIDC.

3. 3

   Compila i campi guidati

   La procedura guidata ti accompagna attraverso i campi specifici del provider: la configurazione dell'emittente, le condizioni di corrispondenza per i JWT in ingresso e i nomi per il service account e la regola di federazione che crea. La procedura guidata precompila oauth_scope=workspace:developer e token_lifetime_seconds=600 (il valore predefinito dell'API quando token_lifetime_seconds viene omesso è 3600); modificali se il tuo workload necessita di uno scope o di una durata diversi.

4. 4

   Verifica l'emittente

   Facoltativamente seleziona Verify issuer per eseguire una prova a secco della configurazione dell'emittente prima che venga creato qualcosa. La verifica conferma che Anthropic può recuperare e analizzare il JWKS dagli URL che hai inserito, il che permette di individuare precocemente errori di raggiungibilità e di configurazione.

5. 5

   Testa la connessione

   La procedura guidata crea l'emittente, il service account e la regola di federazione, quindi resta in ascolto di uno scambio di token riuscito per 15 minuti. Attiva uno scambio dal tuo workload entro quella finestra (vedi Autenticati dal tuo workload) per confermare che la configurazione funzioni. Se la finestra scade, le risorse persistono; puoi rieseguire il test dalla pagina di dettaglio della regola di federazione. Prendi nota dell'ID della regola (fdrl_...) e dell'ID del service account (svac_...) creati dalla procedura guidata: il tuo workload li passa entrambi, insieme all'ID della tua organizzazione (e all'ID del tuo workspace quando la regola copre più di un workspace), in ogni richiesta di scambio token.

Per gestire queste risorse in modo programmatico, consulta Gestisci WIF con l'Admin API per la procedura dettagliata con curl, oppure consulta il riferimento API dei service account, il riferimento API degli emittenti di federazione e il riferimento API delle regole di federazione per i dettagli completi dei parametri e gli schemi di risposta.

Autenticati dal tuo workload

Con la federazione configurata, il tuo workload scambia a runtime il JWT emesso dal suo IdP con un token Anthropic. Gli SDK gestiscono per te lo scambio e il ciclo di rinnovo. La scheda cURL mostra lo scambio HTTP sottostante per script shell, debugging o linguaggi senza supporto SDK.

Costruisci il client SDK

Puoi costruire il client con credenziali esplicite o senza argomenti. Senza argomenti, l'SDK risolve le credenziali dalle variabili d'ambiente o dal profilo attivo, come descritto in Precedenza delle credenziali. La forma senza argomenti è il pattern consigliato per i workload di produzione: distribuisci la stessa immagine container ovunque e inietta ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID e ANTHROPIC_IDENTITY_TOKEN_FILE per ambiente.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

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"))

La risposta dello scambio token segue RFC 6749 §5.1. Consulta Risposta dello scambio token per il riferimento dei campi.

Precedenza delle credenziali

Ogni SDK risolve le credenziali nello stesso ordine a cinque livelli: argomenti del costruttore, poi ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, poi un ANTHROPIC_PROFILE esplicito, poi le variabili d'ambiente di federazione, poi il profilo attivo implicito. La prima sorgente che fornisce una credenziale vince.

Per la tabella completa delle precedenze, la semantica di ciascun livello e lo schema del file di profilo, consulta Precedenza delle credenziali nel riferimento WIF.

Migra dalle chiavi API

Per passare un workload esistente da una chiave API statica alla federazione senza interruzioni:

1. Configura la federazione in parallelo. Completa la procedura di configurazione e conferma che la regola di federazione corrisponda al token del tuo workload. Lascia per ora al suo posto l'ANTHROPIC_API_KEY esistente.
2. Esegui uno smoke test per verificare quale credenziale vince. Esegui ant auth status dall'interno del workload (o ispeziona i log di debug dell'SDK). Poiché ANTHROPIC_API_KEY si trova al di sopra dei livelli di federazione nella catena di precedenza, in questa fase la chiave API vince ancora.
3. Rimuovi ANTHROPIC_API_KEY ovunque venga iniettata. Rimuovila dai segreti CI, dall'ambiente del container e dai profili shell (vedi l'avviso precedente). Riesegui ant auth status e conferma che ora sia selezionata la sorgente di federazione.
4. Elimina la chiave API. Una volta che il workload è in esecuzione con il token federato, elimina la chiave nella Claude Console in Settings → API keys.

Durata e rinnovo del token

La durata del token Anthropic generato è il minore tra (a) il token_lifetime_seconds della regola (predefinito 3.600 secondi) e (b) il doppio della durata residua del JWT dell'IdP che hai presentato. Il risultato non è mai inferiore a 60 secondi. Il secondo limite impedisce che un token Anthropic sopravviva all'identità a monte da cui è stato derivato per più di un piccolo margine.

Gli SDK memorizzano il token nella cache e lo rinnovano secondo una pianificazione a due livelli modellata su botocore:

• Rinnovo consultivo alla scadenza meno 120 secondi. L'SDK tenta un nuovo scambio. Se l'endpoint dei token non è raggiungibile, l'SDK continua a servire il token in cache, che è ancora valido per circa altri 90 secondi.
• Rinnovo obbligatorio alla scadenza meno 30 secondi. Uno scambio fallito a questo punto genera un errore. Il token in cache è troppo vicino alla scadenza per essere sicuro.

Poiché l'SDK rilegge ANTHROPIC_IDENTITY_TOKEN_FILE a ogni scambio, recepisce in modo trasparente i token proiettati ruotati (i token di service account di Kubernetes, ad esempio, ruotano ben prima del loro exp).

Per impostazione predefinita, i token di identità che contengono un claim jti sono monouso: ogni scambio deve presentare un JWT che non sia stato scambiato in precedenza, e ripresentarne uno fallisce con il motivo jti_reused nella pagina della cronologia delle autenticazioni. Se il tuo workload recupera i propri token dal tuo identity provider, genera un JWT nuovo per ogni scambio invece di riutilizzarne uno in cache (i cicli di retry sono il colpevole più comune). Lo stesso vale per un token letto da ANTHROPIC_IDENTITY_TOKEN_FILE: l'SDK rilegge il file a ogni scambio, quindi il file deve contenere un nuovo token prima di ogni rinnovo. Un rinnovo che rilegge un token non ruotato, o un processo riavviato che ripresenta un token già scambiato, viene rifiutato allo stesso modo. Ruotare il token ben entro la durata del token generato mantiene il file in anticipo rispetto alla pianificazione dei rinnovi; se la tua sorgente di token non può ruotare così spesso, puoi disabilitare check_jti per quell'emittente come ultima risorsa (questo rimuove la protezione dal replay per ogni regola dell'emittente). Consulta Verifica JWT per i dettagli.

Identity provider

Ogni guida descrive da dove proviene il JWT su quella piattaforma, che aspetto hanno i suoi claim e la configurazione dell'emittente e della regola da registrare.

Vedi anche

• Gestisci WIF con l'Admin API: crea emittenti, service account e regole dall'infrastructure as code
• Riferimento WIF: variabili d'ambiente, schema del file di profilo, regole di validazione e codici di errore
• Autenticazione: tutte le opzioni di autenticazione negli SDK Anthropic
• Riferimento Admin API: schemi di richiesta e risposta generati per ogni endpoint dell'Admin API