Workload Identity Federation

La "Workload Identity Federation" (federazione delle identità dei workload), o WIF, consente ai tuoi workload di autenticarsi verso l'API di Claude 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 issuer 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 trust che configuri nella Claude Console e restituisce un access token Anthropic a breve durata associato a un service account nella tua organizzazione. Non ci sono segreti statici da generare, archiviare nella CI, ruotare o esporre a fughe.

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 è di per sé una soluzione di sicurezza completa: l'autenticazione federata è sicura solo quanto l'identity provider upstream 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'issuer X, con claim che corrispondono a Y, possono agire come il service account Z."

Service account

Un service account (svac_...) è un'identità non umana con 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 federation rule 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.

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 (fdis_...) registra un identity provider OIDC presso la tua organizzazione. Registrare un issuer comunica ad Anthropic "i JWT firmati da questo provider possono asserire l'identità del workload per la mia organizzazione."

Un issuer 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 (impostazione predefinita) per qualsiasi provider che serve /.well-known/openid-configuration al proprio issuer URL. Usa explicit_url per puntare direttamente a un endpoint JWKS, oppure inline per caricare il set di chiavi per gli issuer non raggiungibili da internet pubblico (ad esempio, un cluster Kubernetes privato).

Gli URL dell'issuer e del JWKS devono essere https, sulla porta 443, e usare un nome host 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 issuer per ambiente: il tuo cluster EKS di produzione, il tuo cluster di staging e GitHub Actions sono tre issuer separati.

Federation rule

Una federation rule (fdrl_...) è il ponte tra un issuer e un service account: "quando un JWT dall'issuer X ha claim che corrispondono 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 modale di creazione tunnel di MCP tunnels crea regole con scope org:manage_tunnels. Consulta Scope OAuth. La regola imposta anche token_lifetime_seconds (da 60 a 86400, predefinito 3600).

Un singolo issuer 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 al 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 access token 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'issuer e alle condizioni di corrispondenza della federation rule, 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.

Configurare la federazione

Ti servono l'accesso admin alla 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 identity token da quel provider.

Nella Claude Console, vai su Settings → Workload identity.

Autenticarsi dal workload

Con la federazione configurata, il tuo workload scambia a runtime il JWT emesso dall'IdP con un token Anthropic. Gli SDK gestiscono per te lo scambio e il ciclo di refresh. La scheda cURL mostra lo scambio HTTP sottostante per script shell, debug 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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 fonte che produce una credenziale vince.

Per la tabella completa della precedenza, 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 downtime:

1. Configura la federazione in parallelo. Completa la procedura di configurazione e verifica che la federation rule corrisponda al token del tuo workload. Lascia per ora in posizione l'ANTHROPIC_API_KEY esistente.
2. Verifica 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 verifica che ora sia selezionata la fonte 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 refresh del token

La durata del token Anthropic generato è il minore tra (a) il token_lifetime_seconds della regola (predefinito 3600 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à upstream da cui è stato derivato per più di un piccolo margine.

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

• Refresh consigliato a scadenza meno 120 secondi. L'SDK tenta un nuovo scambio. Se l'endpoint del token non è raggiungibile, l'SDK continua a servire il token in cache, che è ancora valido per circa altri 90 secondi.
• Refresh obbligatorio a 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 Kubernetes, ad esempio, ruotano 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 di issuer e regola da registrare.

Vedi anche

• 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