Riferimento WIF

Questa pagina raccoglie le superfici di configurazione, i vincoli di convalida e le mappature degli errori per Workload Identity Federation. Per le procedure guidate di configurazione, consulta le guide dei provider.

Richiesta di scambio del token

POST /v1/oauth/token accetta un corpo JSON che utilizza il grant jwt-bearer di RFC 7523. L'SDK costruisce questa richiesta per te a partire dalle variabili d'ambiente; gli esempi cURL in ciascuna guida dei provider mostrano il corpo grezzo.

Risposta dello scambio del token

POST /v1/oauth/token restituisce una risposta token OAuth 2.0 standard (RFC 6749 §5.1):

Variabili d'ambiente

L'SDK legge queste variabili per eseguire uno scambio di token federato senza argomenti del costruttore.

Il percorso di federazione diretto tramite variabili d'ambiente si attiva solo quando ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e una tra ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN sono tutte impostate. ANTHROPIC_WORKSPACE_ID viene letta insieme a queste, ma non condiziona l'attivazione.

Precedenza delle credenziali

L'SDK risolve le credenziali in questo ordine. Vince la prima fonte che fornisce una credenziale.

Nella CLI ant, le impostazioni per Claude Models on Google Cloud (Anthropic managed) hanno una priorità inferiore rispetto alle variabili d'ambiente di federazione e superiore rispetto al profilo attivo. Le impostazioni sono il progetto, l'ID del workspace e la località. Puoi impostarle con i flag --google-cloud-* o con le variabili ANTHROPIC_GOOGLE_CLOUD_*. La CLI usa queste impostazioni quando almeno una di esse è impostata. Con queste impostazioni, la CLI ottiene le proprie credenziali da Google Application Default Credentials.

Quando viene caricato un profilo, le variabili d'ambiente compilano i campi che il profilo omette, ma non sovrascrivono mai i campi che il profilo imposta esplicitamente. Ad esempio, ANTHROPIC_WORKSPACE_ID compila workspace_id solo quando il profilo attivo non lo imposta.

File di configurazione del profilo

Un profilo è un file di configurazione con nome che viene letto sia dall'SDK sia dalla CLI ant. I profili ti consentono di distribuire i parametri di federazione con l'immagine del container o di passare da un ambiente all'altro senza modificare il codice.

Directory di configurazione

L'SDK individua la directory di configurazione in questo ordine:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic su Linux e macOS
3. %APPDATA%\Anthropic su Windows

Profilo attivo

Il nome del profilo attivo viene risolto in questo ordine:

1. $ANTHROPIC_PROFILE
2. Il contenuto di <config_dir>/active_config (un file di una riga scritto da ant profile activate <name>)
3. Il nome letterale default

Claude Code e il Claude Agent SDK rispettano lo stesso ordine di risoluzione, quindi un profilo di federazione configurato qui autentica anche questi strumenti senza configurazione aggiuntiva.

Struttura dei file

Sia il file di configurazione sia il file delle credenziali contengono un campo stringa version di primo livello nel formato major.minor (attualmente "1.0"). L'SDK scrive questo campo automaticamente in modo che le versioni future possano rilevare e migrare i formati precedenti; omettilo quando scrivi una configurazione a mano e l'SDK tratterà il file come versione corrente.

Esempio di profilo di federazione

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Se authentication.identity_token viene omesso, l'SDK ricorre a ANTHROPIC_IDENTITY_TOKEN_FILE o ANTHROPIC_IDENTITY_TOKEN dall'ambiente.

Ambiti OAuth

L'oauth_scope impostato su una regola di federazione determina quali endpoint della Claude API può chiamare il token di accesso emesso.

Una richiesta a un endpoint al di fuori dell'ambito del token restituisce HTTP 403. Ambiti più granulari (per risorsa, o lettura rispetto a scrittura) non sono attualmente disponibili.

Limiti dei permessi

L'oauth_scope di una regola di federazione è un tetto massimo: il token emesso non può mai superarlo. L'organization_role dell'account di servizio di destinazione (developer o admin) determina quali ambiti sono concedibili, quindi una regola che concede org:admin deve avere come destinazione un account di servizio con organization_role=admin. I permessi effettivi sono l'intersezione tra l'ambito della regola e il ruolo dell'account di servizio.

Regole di convalida

Anthropic applica questi vincoli quando crei o aggiorni issuer e regole, e quando verifica un JWT in ingresso al momento dello scambio.

Per i dettagli completi sui parametri e gli schemi di risposta, consulta il riferimento API degli account di servizio, il riferimento API degli issuer di federazione e il riferimento API delle regole di federazione.

Campi delle risorse

Campi URL

I campi issuer_url, jwks.discovery_base e jwks.url vengono convalidati:

Gli errori di convalida degli URL restituiscono 400 invalid_request_error con il nome del campo come prefisso nel messaggio di errore (ad esempio, issuer_url: url must use https scheme).

Verifica del JWT

Semantica di corrispondenza delle regole

Il blocco match di una regola di federazione determina se un JWT in ingresso viene accettato. Tutti i campi compilati vengono valutati con semantica AND: il JWT deve soddisfare ogni matcher compilato. Deve essere impostato almeno uno tra subject_prefix, claims o condition; un blocco match che contiene solo audience (o nessun matcher) viene rifiutato. Questo protegge da regole che accetterebbero ogni token di un issuer.

Ambiente di valutazione CEL

L'espressione condition ha accesso a una singola variabile:

Esempio:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Errori

Errori dello scambio del token

POST /v1/oauth/token restituisce gli errori nel formato di errore API standard. L'SDK segnala un errore di scambio come WorkloadIdentityError, che fornisce lo stato HTTP e i dettagli dell'errore dal corpo della risposta. L'ID della richiesta si trova sull'errore in Python, TypeScript e Ruby, e nelle intestazioni di risposta dell'eccezione in Java. In Go si trova solo nel messaggio dell'errore, perché il tipo dell'errore si trova in un pacchetto interno; gli errori C# e PHP non lo contengono.

Ogni rifiuto di un'asserzione restituisce lo stesso 401 authentication_error opaco con il messaggio fisso Authentication failed, indipendentemente da quale verifica non sia riuscita; un errore distinguibile consentirebbe a un chiamante di sondare la configurazione della regola. Il motivo del rifiuto viene registrato nella voce del tentativo nella cronologia di autenticazione nella Claude Console, ad esempio match_subject_prefix quando il claim sub non soddisfa il subject_prefix della regola, oppure workspace_id_required quando la regola si estende su più workspace e la richiesta non ne indica nessuno. Le richieste rifiutate prima che l'organizzazione della regola venga confermata (la famiglia 400 invalid_request_error sopra) non lasciano alcuna voce nella cronologia; i loro messaggi di risposta indicano direttamente il problema. Un 401 senza una voce corrispondente nella cronologia di solito significa che il federation_rule_id stesso non è stato riconosciuto.

Errori comuni lato SDK

Risolvere i problemi di uno scambio non riuscito

Una risposta 401 authentication_error è intenzionalmente opaca e il suo messaggio è sempre Authentication failed; il motivo del rifiuto viene registrato nella cronologia di autenticazione, non nella risposta.

Un errore opaco comune è un'asserzione riutilizzata: un'asserzione che contiene un claim jti può essere scambiata una sola volta, quindi un carico di lavoro che invia di nuovo lo stesso JWT (un ciclo di tentativi, o un aggiornamento che rilegge un token non ruotato) viene rifiutato al secondo scambio. La pagina della cronologia di autenticazione mostra questi tentativi con il motivo jti_reused; la soluzione è emettere una nuova asserzione per ogni scambio.

Se devi comunque eseguire il debug a partire dal JWT stesso, esegui queste verifiche nell'ordine:

1. 1

   Decodifica il JWT

   Decodifica l'asserzione che hai inviato in modo da poter confrontare ogni claim con la configurazione dell'issuer e della regola:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Verifica che iss corrisponda all'issuer

   Il claim iss decodificato deve essere uguale byte per byte all'issuer_url registrato, inclusi schema, porta ed eventuale barra finale. Una differenza anche di un solo carattere fa fallire la verifica.

3. 3

   Verifica che aud corrisponda alla regola

   Il claim aud decodificato deve contenere il valore audience della regola come corrispondenza esatta. Quando aud è un array, un elemento deve corrispondere esattamente.

4. 4

   Verifica sub e ogni voce di claims

   Confronta sub con il subject_prefix della regola (distingue tra maiuscole e minuscole; un * finale indica una corrispondenza di prefisso, qualsiasi altro valore è esatto). Confronta ogni chiave della mappa claims della regola con il claim di primo livello con lo stesso nome.

5. 5

   Verifica exp, nbf e iat

   exp deve essere nel futuro e nbf/iat devono essere nel passato, entro la finestra di sfasamento di 30 secondi. Se l'orologio dell'host del carico di lavoro ha subito una deriva, un token altrimenti valido viene rifiutato.

6. 6

   Verifica la raggiungibilità del JWKS

   Per la modalità discovery, recupera <jwks.discovery_base or issuer_url>/.well-known/openid-configuration tramite HTTPS pubblico sulla porta 443 e verifica che jwks_uri venga risolto. Per explicit_url, recupera direttamente l'URL del JWKS. Per inline, verifica che la chiave di firma dell'issuer non sia stata ruotata da quando hai registrato le chiavi.

   Se l'issuer ha ruotato la propria chiave di firma e ha iniziato immediatamente a firmare con essa, gli scambi possono non riuscire per un massimo di un minuto mentre la cache JWKS di Anthropic si aggiorna. Consulta Rotazione delle chiavi e caching.

Modalità di origine del JWKS

Quando registri un issuer di federazione, il campo jwks controlla il modo in cui Anthropic ottiene le chiavi pubbliche utilizzate per verificare le firme dei JWT di quell'issuer. Si tratta di un'unione discriminata con chiave type:

L'unione discriminata rende i campi associati mutuamente esclusivi per costruzione. Sia discovery sia explicit_url accettano anche una stringa facoltativa ca_cert_pem per gli issuer che servono TLS da una CA privata.

Rotazione delle chiavi e caching

Nelle modalità discovery ed explicit_url, Anthropic memorizza nella cache il JWKS recuperato. Se il tuo provider di identità pubblica una nuova chiave di firma e inizia immediatamente a firmare token con essa, gli scambi che presentano tali token possono non riuscire con un errore di firma per un massimo di 1 minuto mentre la cache si aggiorna.

Per evitare questa finestra, pubblica una nuova chiave di firma nel JWKS almeno 15 minuti prima che il tuo provider di identità inizi a firmare token con essa, e mantieni la chiave sostituita nel JWKS finché i token da essa firmati non sono scaduti. I provider di identità gestiti in genere seguono autonomamente questa disciplina. Se gestisci un tuo issuer (un cluster Kubernetes autogestito, un provider di discovery OIDC SPIRE o un server di autorizzazione personalizzato Okta con una cadenza di rotazione configurata), verifica che la tua politica di rotazione pubblichi le nuove chiavi prima del primo utilizzo.