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 guidate di configurazione, consulta le guide dei provider.

Richiesta di scambio token

POST /v1/oauth/token accetta un corpo JSON che utilizza il grant jwt-bearer di RFC 7523. Gli SDK costruiscono 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 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 alle altre ma non condiziona l'attivazione.

Precedenza delle credenziali

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

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 con nome che sia l'SDK sia la CLI ant leggono. 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 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 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.

Scope OAuth

L'oauth_scope che imposti su una regola di federazione determina quali endpoint della Claude API può chiamare l'access token emesso.

Una richiesta a un endpoint al di fuori dello scope del token restituisce HTTP 403. Scope 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 del service account di destinazione (developer o admin) determina quali scope sono concedibili, quindi una regola che concede org:admin deve avere come destinazione un service account con organization_role=admin. I permessi effettivi sono l'intersezione tra lo scope della regola e il ruolo del service account.

Regole di validazione

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 dei parametri e gli schemi di risposta, consulta il riferimento API dei service account, il riferimento API dei federation issuer e il riferimento API delle federation rule.

Campi delle risorse

Campi URL

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

Gli errori di validazione degli URL restituiscono 400 invalid_request_error con il nome del campo come prefisso del 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 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 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 di scambio token

POST /v1/oauth/token restituisce errori nel formato di errore API standard. L'SDK incapsula gli errori di scambio in un FederationExchangeError tipizzato (o equivalente nel linguaggio) che espone lo stato HTTP, il corpo della risposta e il request_id.

Ogni rifiuto di un'assertion restituisce lo stesso 401 authentication_error opaco con il messaggio fisso Authentication failed, indipendentemente da quale verifica sia fallita; un errore distinguibile permetterebbe a un chiamante di sondare la configurazione della regola. Il motivo del rifiuto viene registrato nella voce del tentativo nella cronologia di autenticazione, ad esempio match_subject_prefix quando il claim sub non soddisfa il subject_prefix della regola, oppure workspace_id_required quando la regola copre più workspace e la richiesta non ne indica nessuno. Le richieste rifiutate prima che l'organizzazione della regola sia 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 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 errore opaco comune è un'assertion riprodotta: un'assertion che contiene un claim jti può essere scambiata una sola volta, quindi un workload che reinvia lo stesso JWT (un ciclo di retry, o un rinnovo 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 assertion per ogni scambio.

Se hai ancora bisogno di eseguire il debug a partire 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 ed eventuale slash finale. Una differenza di 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 workload 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 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 propria chiave di firma e ha iniziato immediatamente a firmare con essa, gli scambi possono fallire per un massimo di un minuto mentre la cache JWKS di Anthropic si aggiorna. Consulta Rotazione delle chiavi e cache.

Modalità di origine JWKS

Quando registri un federation issuer, il campo jwks controlla il modo in cui Anthropic ottiene le chiavi pubbliche utilizzate per verificare le firme dei JWT di quell'issuer. È 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 cache

Nelle modalità discovery ed explicit_url, Anthropic mantiene in cache il JWKS recuperato. Se il tuo identity provider pubblica una nuova chiave di firma e inizia immediatamente a firmare 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 token con essa, e mantieni la chiave sostituita nel JWKS finché i token che ha firmato non sono scaduti. Gli identity provider gestiti in genere seguono autonomamente questa disciplina. Se gestisci il tuo issuer (un cluster Kubernetes autogestito, un provider di discovery OIDC SPIRE o un authorization server personalizzato Okta con una cadenza di rotazione configurata), conferma che la tua policy di rotazione pubblichi le nuove chiavi prima del primo utilizzo.