Workload Identity Federation: addio API key statiche, benvenuti token che scadono

Ok, parliamo chiaro: avete presente quelle API key che iniziano con sk-ant-... che vi portate dietro ovunque? Quelle che finite per copiaincollare nei file .env, nei secret manager, nelle variabili CI/CD, e che ogni volta vi fate venire l’ansia pensando “e se qualcuno le trova”?

Anthropic ha appena rilasciato Workload Identity Federation (WIF), e fondamentalmente risolve questo problema. Invece di usare chiavi statiche che vivono per sempre, i vostri workload si autenticano con token temporanei emessi dal vostro identity provider – quello che già usate, tipo AWS IAM, Google Cloud, GitHub Actions, Kubernetes, o qualsiasi cosa parli OIDC standard.

Come funziona nella pratica

Il meccanismo è abbastanza elegante. Il vostro workload presenta un JWT firmato dal vostro IdP. Anthropic lo valida contro le regole che avete configurato nella Console e vi restituisce un access token di breve durata legato a un service account nella vostra org. Zero segreti statici da mintare, salvare, ruotare o – peggio – far leakare.

Tre passaggi fondamentali:

Il vostro IdP emette un JWT al workload (su Kubernetes è un projected service-account token, su GCP il metadata server, su Azure l’IMDS, su GitHub Actions l’endpoint OIDC)
L’SDK scambia il JWT con un token Anthropic via POST /v1/oauth/token usando il grant jwt-bearer dell’RFC 7523
L’SDK usa quel token per ogni richiesta e lo rigenera prima che scada

Il bello? Nel vostro codice costruite il client senza api_key e chiamate l’API normalmente. L’SDK gestisce tutto il ciclo di refresh in background.

I tre pezzi del puzzle

Prima che un workload possa federarsi, configurate tre risorse nella Console. Insieme esprimono “token firmati dall’issuer X, con claim che sembrano Y, possono agire come service account Z”.

Service account

Un service account (svac_...) è un’identità non-umana dentro la vostra org Anthropic. È il principale che un token federato impersona. Vivono a livello organizzazione e diventano attivi in un workspace quando li aggiungete ai membri di quel workspace.

La differenza chiave rispetto a un’API key: un’API key è una credential, mentre un service account ha credential mintate on-demand. Potete fare audit di quali workload hanno agito come quale service account.

Federation issuer

Un federation issuer (fdis_...) registra un identity provider OIDC con la vostra org. Registrare un issuer dice ad Anthropic “JWT firmati da questo provider possono asserire workload identity per la mia org”.

Due pezzi di configurazione:

Issuer URL: il valore esatto del claim iss che appare nei JWT del provider (tipo https://token.actions.githubusercontent.com)
JWKS source: come Anthropic recupera le chiavi pubbliche per verificare le firme JWT. Usate discovery (default) per provider che servono /.well-known/openid-configuration, explicit_url per puntare direttamente a un endpoint JWKS, o inline per caricare il key set manualmente

Federation rule

Una federation rule (fdrl_...) è il ponte tra issuer e service account: “quando un JWT dall’issuer X ha claim che sembrano Y, minta un token per il service account Z con scope S”.

Una rule definisce condizioni di match, un target, e lo scope di autorizzazione:

Match: condizioni che un JWT in ingresso deve soddisfare. Potete matchare su subject_prefix, audience esatto, mappa di claim values, o espressioni CEL per logica complessa
Target: il service account a cui il JWT matchato viene mappato
Authorization: lo scope OAuth sul token mintato (al lancio sempre workspace:developer) e token_lifetime_seconds (60-86400, default 3600)

Setup pratico

Servono accesso admin alla vostra org Anthropic, un identity provider OIDC-capable con endpoint JWKS raggiungibile, e un workload che possa ottenere un identity token da quel provider.

Nella Console, andate su Settings → Workload identity:

1. Registrate un issuer

Tab Issuers, Create issuer. Nome tipo prod-eks o gha, Issuer URL (il claim iss esatto dei JWT del vostro IdP), JWKS source (discovery per la maggior parte dei managed IdP).

La Console include preset per AWS e Google Cloud che precompilano pattern e rule default, più un’opzione OIDC generica per tutto il resto.

2. Create un service account

Settings → Service accounts → Create service account. Nome tipo inference-worker o ci-deploy. Questa è l’identità che i vostri token mintati impersoneranno. Aggiungete il service account a ogni workspace in cui dovrebbe agire dalla pagina Members di quel workspace. Annotatevi l’ID (svac_...).

3. Create una federation rule

Tab Federation rules, Create rule. Selezionate l’issuer dello step 1, configurate le condizioni di match (siate specifici quanto i claim del vostro IdP vi permettono – una rule troppo larga garantisce più accesso di quanto intendiate), selezionate il service account dello step 2, impostate scope e token lifetime. Annotatevi l’ID della rule (fdrl_...) – il vostro workload lo passa in ogni richiesta di token exchange.

Autenticare dal workload

Con la federation configurata, il vostro workload scambia il suo JWT IdP-issued con un token Anthropic a runtime. Gli SDK gestiscono l’exchange e il refresh loop per voi.

Potete costruire il client con credential esplicite o senza argomenti. Senza argomenti, l’SDK risolve le credential da variabili d’ambiente o dal profilo attivo. La forma zero-argument è il pattern raccomandato per production: shippate la stessa container image ovunque e iniettate ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, e ANTHROPIC_IDENTITY_TOKEN_FILE per ambiente.

Migrare da API key

Per switchare un workload esistente da API key statica a federation senza downtime:

Configure federation in parallelo – completate il walkthrough e confermate che la rule matcha il token del vostro workload. Lasciate ANTHROPIC_API_KEY in place per ora
Smoke-test quale credential vince – girate ant auth status dal workload. Siccome ANTHROPIC_API_KEY sta sopra i tier di federation nella precedence chain, l’API key vince ancora a questo stage
Unsettate ANTHROPIC_API_KEY ovunque sia iniettata – rimuovetela da CI secrets, container environment, shell profiles
Revocate l’API key – una volta che il workload gira sul federated token, cancellate la key nella Console sotto Settings → API keys

Token lifetime e refresh

Il lifetime del token Anthropic mintato è il minore tra il token_lifetime_seconds della rule (default 3600) e il doppio del lifetime rimanente del JWT IdP che avete presentato, con floor di 60 secondi. Questo previene che un token Anthropic sopravviva all’identità upstream da cui deriva per più di un piccolo margine.

Gli SDK cachano il token e lo refreshano su uno schedule a due tier:

Advisory refresh a scadenza meno 120 secondi – l’SDK tenta un nuovo exchange. Se il token endpoint è unreachable, l’SDK continua a servire il token cachato, che è ancora valido per circa 90 secondi
Mandatory refresh a scadenza meno 30 secondi – un exchange fallito a questo punto solleva errore

Siccome l’SDK rilegge ANTHROPIC_IDENTITY_TOKEN_FILE a ogni exchange, pickup automaticamente i projected token ruotati (i service-account token Kubernetes, per esempio, ruotano ben prima del loro exp).

Perché importa

WIF rinforza la vostra security posture rimuovendo credential statiche dalla superficie di Anthropic e rimpiazzandole con token che scadono in minuti invece che mai. Non è una storia di security completa da sola – l’autenticazione federata è solida quanto l’identity provider upstream che firma il JWT. Accoppiate WIF con i controlli che il vostro IdP già supporta (workload identity binding, conditional access, audit logging) per defense in depth.

La documentazione copre setup specifici per AWS (STS web identity tokens, EKS IRSA projected tokens), Google Cloud (Google-signed identity tokens via metadata server), Microsoft Azure (Managed Identity IMDS e Entra Workload ID su AKS), GitHub Actions (keyless CI auth con Actions OIDC token), Kubernetes (cluster self-managed e on-premises con projected service-account tokens), e Okta (service applications usando client-credentials flow).