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 è una soluzione di sicurezza completa di per sé: 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 (workload identity binding, 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 assomigliano a Y, possono agire come service account Z."



Service account

Un service account (svac_...) è un'identità non umana con un nome all'interno della tua organizzazione Anthropic. È il principal per conto del quale agisce 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 a 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.

La distinzione chiave rispetto a una chiave API: una chiave API è una credenziale, mentre un service account ha credenziali generate per esso su richiesta. Puoi verificare quali workload hanno agito come quale service account.



Federation issuer

Un federation issuer (emittente di federazione, fdis_...) registra un identity provider OIDC presso la tua organizzazione. Registrare un emittente dice 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:

• Issuer URL: 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.
• JWKS source: Come 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 suo issuer URL. 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 risolve 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.



Federation rule

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 assomigliano a 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:

• Match: Le condizioni che un JWT in ingresso deve soddisfare. Puoi fare corrispondenza su un subject_prefix (ad esempio, system:serviceaccount:prod:worker, o con un * finale per una corrispondenza di prefisso), un audience esatto, una mappa di valori di claim esatti, un'espressione condition in CEL per logiche complesse, 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.
• Authorization: Lo scope OAuth concesso sul token generato. Il valore predefinito è workspace:developer, che concede lo stesso accesso di una chiave API emessa per quel workspace. Alcuni prodotti bloccano lo scope quando crei una regola dal loro flusso; ad esempio, la finestra di creazione tunnel degli MCP tunnels crea regole con scope workspace:manage_tunnels. Consulta OAuth scopes. 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 autorizzazione. 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 i suoi claim sub e altri 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 aggiorna 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.



Configurare la federazione

Hai bisogno del ruolo admin, owner o primary owner nella tua organizzazione Anthropic, di un identity provider compatibile con OIDC con un endpoint JWKS raggiungibile (o un documento JWKS che puoi incollare, per cluster air-gapped), e di un workload che possa 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.

Per gestire queste risorse in modo programmatico, consulta Gestire WIF con l'Admin API per la guida passo passo con curl, oppure consulta il riferimento API dei service account, il riferimento API dei federation issuer e il riferimento API delle federation rule per i dettagli completi dei parametri e gli schemi di risposta.



Autenticarsi dal tuo workload

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



Costruire 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 di token segue RFC 6749 §5.1. Consulta Token exchange response 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 produce una credenziale vince.

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



Migrare dalle chiavi API

Per passare un workload esistente da una chiave API statica alla federazione senza tempi di inattività:

1. Configura la federazione in parallelo. Completa la guida alla configurazione e conferma che la regola di federazione corrisponda al token del tuo workload. Lascia per ora la ANTHROPIC_API_KEY esistente al suo posto.
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 sopra i livelli di federazione nella catena di precedenza, la chiave API vince ancora in questa fase.
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 venga selezionata la sorgente di federazione.
4. Revoca 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 aggiornamento 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 a un token Anthropic di sopravvivere all'identità a monte da cui è stato derivato per più di un piccolo margine.

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

• Aggiornamento 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.
• Aggiornamento 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, rileva in modo trasparente i token proiettati ruotati (i token di service account di Kubernetes, ad esempio, vengono ruotati ben prima del loro exp).



Identity provider

Ogni guida spiega da dove proviene il JWT su quella piattaforma, come appaiono i suoi claim e la configurazione dell'emittente e della regola da registrare.



Vedi anche

• Gestire WIF con l'Admin API: crea emittenti, service account e regole da 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 di Anthropic
• Riferimento Admin API: schemi di richiesta e risposta generati per ogni endpoint dell'Admin API