Riferimento WIF

Questa pagina raccoglie le superfici di configurazione, i vincoli di validazione e le mappature degli errori per Workload Identity Federation. Per le procedure 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 di 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 ad esse ma non condiziona l'attivazione.

Precedenza delle credenziali

L'SDK risolve le credenziali in questo ordine. La prima sorgente che fornisce una credenziale vince.

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

File di configurazione del profilo

Un profilo è un file di configurazione nominato che sia l'SDK sia la CLI ant leggono. I profili ti permettono di distribuire i parametri di federazione con l'immagine del tuo 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 si risolve 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 questo stesso ordine di risoluzione, quindi un profilo di federazione configurato qui autentica anche quegli 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 in formato major.minor (attualmente "1.0"). L'SDK scrive questo campo automaticamente in modo che le versioni future possano rilevare e migrare i formati più vecchi; omettilo quando scrivi una configurazione a mano e l'SDK tratta il file come la 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 che imposti su una regola di federazione determina quali endpoint dell'API Claude il token di accesso generato può chiamare.

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 limite massimo: il token generato non può mai superarlo. L'organization_role del service account di destinazione (developer o admin) determina quali ambiti sono concedibili, quindi una regola che concede org:admin deve puntare a un service account con organization_role=admin. I permessi effettivi sono l'intersezione dell'ambito della regola e del ruolo del service account.

Regole di validazione

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

Per i dettagli completi dei parametri e gli schemi di risposta, consulta il riferimento API dei service account, 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 validati:

I fallimenti di validazione dell'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 arrivo viene accettato. Tutti i campi popolati vengono valutati con semantica AND: il JWT deve soddisfare ogni matcher popolato. Almeno uno tra subject_prefix, claims o condition deve essere impostato; un blocco match che contiene solo audience (o nessun matcher) viene rifiutato. Questo protegge dalle regole che accetterebbero ogni token da 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 di scambio del token

POST /v1/oauth/token restituisce gli errori nel formato di errore dell'API standard. L'SDK racchiude gli errori di scambio in un WorkloadIdentityError tipizzato che espone lo stato HTTP, il corpo della risposta e il request_id.

Ogni rifiuto di assertion 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.

Fallimenti comuni lato SDK

Risolvere i problemi di uno scambio fallito

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 fallimento opaco comune è un'assertion riutilizzata: un'assertion che contiene un claim jti può essere scambiata solo una volta, quindi un carico di lavoro che reinvia lo stesso JWT (un ciclo di retry, o un refresh 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 è generare un'assertion nuova per ogni scambio.

Se hai ancora bisogno di eseguire il debug dal JWT stesso, esegui queste verifiche in ordine:

1. 1

   Decodifica il JWT

   Decodifica l'assertion che hai inviato in modo da poter confrontare ogni claim con la configurazione del tuo issuer e della tua 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 all'issuer_url registrato byte per byte, inclusi schema, porta e qualsiasi barra finale. Una discrepanza su un singolo 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 (sensibile alle maiuscole; un * finale è una corrispondenza per prefisso, qualsiasi altra cosa è esatta). Confronta ogni chiave nella 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 scostamento di 30 secondi. Se l'orologio dell'host del carico di lavoro è andato alla 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 conferma che jwks_uri si risolva. Per explicit_url, recupera direttamente l'URL del JWKS. Per inline, conferma che la chiave di firma dell'issuer non sia stata ruotata da quando hai registrato le chiavi.

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

Modalità delle sorgenti JWKS

Quando registri un issuer di federazione, il campo jwks controlla come Anthropic ottiene le chiavi pubbliche usate per verificare le firme JWT di quell'issuer. È un'unione discriminata basata su type:

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

Rotazione e caching delle chiavi

Nelle modalità discovery ed explicit_url, Anthropic memorizza nella cache il JWKS recuperato. Se il tuo identity provider pubblica una nuova chiave di firma e inizia immediatamente a firmare i token con essa, gli scambi che presentano quei token possono fallire 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 identity provider inizi a firmare i token con essa, e mantieni la chiave sostituita nel JWKS finché i token che ha firmato non sono scaduti. Gli identity provider gestiti seguono tipicamente questa disciplina da soli. Se gestisci il 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), conferma che la tua policy di rotazione pubblichi le nuove chiavi prima del primo utilizzo.