AmministrazioneAutenticazione

Riferimento WIF

Variabili d'ambiente, regole di validazione, configurazione dei profili e riferimento agli errori per Workload Identity Federation.

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 del provider mostrano il corpo grezzo.

Campo	Obbligatorio	Descrizione
`grant_type`	Sì	Sempre `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Sì	Il JWT OIDC emesso dal tuo identity provider.
`federation_rule_id`	Sì	ID con tag (`fdrl_...`) della regola di federazione da valutare.
`organization_id`	Sì	UUID della tua organizzazione Anthropic.
`service_account_id`	Sì	ID con tag (`svac_...`) del service account di destinazione.
`workspace_id`	Condizionale	ID con tag (`wrkspc_...`) del workspace a cui limitare l'ambito del token emesso, oppure il valore letterale `default` per il workspace predefinito dell'organizzazione. Obbligatorio quando la regola è abilitata per più di un workspace. Se omesso, il server seleziona l'unico workspace abilitato della regola.

Risposta dello scambio token

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

Campo	Tipo	Descrizione
`access_token`	string	Il token Anthropic a breve durata, con prefisso `sk-ant-oat01-...`. Passalo come `Authorization: Bearer <token>`.
`token_type`	string	Sempre `Bearer`.
`expires_in`	integer	Secondi fino alla scadenza del token.
`scope`	string	Lo scope OAuth concesso dalla regola corrispondente.

Variabili d'ambiente

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

Variabile	Obbligatoria	Descrizione	Esempio
`ANTHROPIC_FEDERATION_RULE_ID`	Sì	ID con tag della regola di federazione da valutare.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Sì	UUID della tua organizzazione Anthropic. Lo trovi nella Claude Console in Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Una tra `_TOKEN_FILE` o `_TOKEN`	Percorso del filesystem al JWT emesso dal tuo "identity provider" (provider di identità), o IdP. L'SDK rilegge questo file a ogni scambio in modo che i token proiettati che ruotano su disco siano sempre aggiornati.	`/var/run/secrets/anthropic.com/token`

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.

Una variabile impostata su una stringa vuota occupa comunque il suo posto nella catena di precedenza delle credenziali. Se ANTHROPIC_API_KEY="" è esportata, l'SDK seleziona il percorso della chiave API con una chiave vuota anziché passare alla federazione. Rimuovi le variabili di credenziali inutilizzate anziché svuotarle.

Precedenza delle credenziali

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

Ordine	Sorgente	Note
1	Argomento del costruttore (`api_key=`, `auth_token=`, `credentials=`)	Sovrascrive sempre tutto il resto.
2	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`	Oscura completamente la federazione. Rimuovi queste variabili quando migri dalle chiavi API.
3	`ANTHROPIC_PROFILE`	Carica `<config_dir>/configs/<name>.json`. Un profilo nominato mancante è un errore, non un passaggio alla sorgente successiva.
4	Variabili d'ambiente di federazione	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + + .

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 consentono di distribuire i parametri di federazione con la tua immagine 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:

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

Profilo attivo

Il nome del profilo attivo viene risolto in questo ordine:

$ANTHROPIC_PROFILE
Il contenuto di <config_dir>/active_config (un file di una riga scritto da ant profile activate <name>)
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.

Layout dei file

Percorso	Contenuto	Sensibilità
`<config_dir>/configs/<profile>.json`	`version`, il blocco `authentication`, `organization_id`, `workspace_id` e `base_url`.	Non segreto. Sicuro da committare o includere in un'immagine.
`<config_dir>/credentials/<profile>.json`	`version`, l'`access_token` memorizzato nella cache, `expires_at` e (per il login interattivo) `refresh_token`.	Segreto. Scritto dall'SDK con modalità `0600`.

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 precedenti; omettilo quando crei una configurazione a mano e l'SDK tratterà il file come la versione corrente.

Esempio di profilo di federazione

configs/production.json

{
  "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 è 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 dell'API Claude può chiamare l'access token emesso.

Scope	Concede accesso a
`workspace:developer`	Tutti gli endpoint non amministrativi dell'API Claude nel workspace della regola: Messages (inclusi streaming e conteggio dei token), Models, Managed Agents e le loro sessioni, Files e Skills. Questo corrisponde all'accesso che ha una chiave API emessa per lo stesso workspace.
`org:manage_tunnels`	L'API dei tunnel MCP: elencare e ottenere tunnel, registrare e archiviare certificati CA, rivelare e ruotare il token del tunnel e archiviare tunnel. La finestra modale di creazione tunnel della Console blocca questo scope quando crei una regola da essa.

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.

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.

Campi delle risorse

Campo	Vincolo
`name` di issuer, regola e service account	Deve corrispondere a `^[a-z0-9-]+$`, lunghezza da 1 a 255 caratteri.
`workspace_id`	Opzionale. Il workspace (`wrkspc_...`) la cui quota, fatturazione e limiti di velocità si applicano ai token emessi sotto questa regola. Deve essere un workspace nella stessa organizzazione e il service account di destinazione deve essere membro di quel workspace. Può essere omesso per le regole configurate per un solo workspace.
`token_lifetime_seconds`	Intero tra `60` e `86400` (da 1 minuto a 24 ore). Predefinito `3600`. I valori al di fuori di questo intervallo vengono rifiutati al momento della richiesta. Consulta Durata e refresh del token.

Campi URL

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

Vincolo	Dettaglio
Schema	Deve essere `https`.
Porta	Deve essere `443` (esplicita o predefinita).
Host	Deve essere un nome host DNS pubblico per il tuo provider OIDC. Deve risolversi in indirizzi IP pubblici; i letterali IP non sono accettati.

Gli errori di validazione 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).

I vincoli URL si applicano solo agli URL che Anthropic contatta. Nelle modalità JWKS explicit_url e inline, e nella modalità discovery quando jwks.discovery_base è impostato, l'issuer_url viene confrontato con il claim iss del JWT come stringa e non viene mai recuperato, quindi può fare riferimento a un hostname interno o a una porta non standard.

Verifica JWT

Vincolo	Dettaglio
Dimensione massima	Il JWT `assertion` deve essere al massimo 16 KiB.
Algoritmo di firma	Sono accettati solo algoritmi asimmetrici (famiglie RSA ed ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) e `none` vengono rifiutati.
Key ID	L'header del JWT deve contenere un `kid` che corrisponda a una chiave nel JWKS dell'issuer. I token senza `kid` vengono rifiutati.
Claim obbligatori	`sub` deve essere presente. `iat` deve essere presente e non nel futuro. `exp` deve essere presente e nel futuro.
Durata massima	La durata del token ( meno ) non deve superare il massimo configurato dell'issuer (1 ora per impostazione predefinita, configurabile per ciascun issuer nella Claude Console).

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 da un issuer.

Matcher	Tipo	Semantica
`subject_prefix`	string	Corrispondenza esatta con il claim `sub` del JWT. Un `` finale lo rende una corrispondenza per prefisso (il valore `sub` deve iniziare con i caratteri prima del ``). Case-sensitive.
`audience`	string	Il claim `aud` del JWT deve contenere esattamente questa stringa. Quando `aud` è un array, qualsiasi elemento che corrisponde esattamente soddisfa il controllo.
`claims`	map<string, string>	Ogni chiave è un nome di claim di primo livello e ogni valore è il valore stringa esatto richiesto. Per claim annidati, numerici, booleani o complessi come liste e mappe, usa invece `condition` con un'espressione CEL.

Ambiente di valutazione CEL

L'espressione condition ha accesso a una singola variabile:

Variabile	Tipo	Contenuto
`claims`	map	L'intero set di claim JWT decodificato. Gli oggetti annidati sono accessibili come mappe annidate.

Esempio:

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

Le condizioni CEL sono confini di sicurezza. Un'espressione che valuta a true per più input del previsto concede un accesso più ampio del previsto. Preferisci i matcher statici quando esprimono il tuo vincolo.

Errori

Errori di scambio token

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

Stato	Errore	Causa	Risoluzione
400	`invalid_request`	`federation_rule_id` è malformato o manca un campo obbligatorio della richiesta.	Verifica l'ID `fdrl_` e che il corpo della richiesta includa tutti i campi obbligatori.
400	`invalid_request`	`workspace_id_required`: la regola di federazione è abilitata per più di un workspace e la richiesta omette `workspace_id`.	Imposta `ANTHROPIC_WORKSPACE_ID` (o il campo `workspace_id` nel corpo di una richiesta grezza) sull'ID `wrkspc_...` a cui vuoi limitare l'ambito del token. Consulta Richiesta di scambio token.
400

Tutti i fallimenti invalid_grant restituiscono HTTP 400; la causa specifica viene registrata solo lato server e non esposta nella risposta.

Fallimenti comuni lato SDK

Sintomo	Causa	Risoluzione
L'SDK segnala "no credentials" invece di eseguire lo scambio	Una tra `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` non è impostata e nessun profilo è attivo.	Imposta tutte e quattro le variabili, oppure configura un profilo.
L'SDK si autentica con una chiave API invece di federare	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` è impostata e vince la precedenza.	Rimuovi la variabile della chiave o del token.
`FileNotFoundError` alla prima richiesta	Il percorso in `ANTHROPIC_IDENTITY_TOKEN_FILE` non esiste. L'SDK apre il file in modo lazy al momento dello scambio.	Conferma che il volume del token proiettato sia montato e che il percorso corrisponda.
Lo scambio token ha successo ma una richiesta all'API Claude restituisce 403

Risolvere i problemi di uno scambio fallito

Una risposta 400 invalid_grant è intenzionalmente opaca; la causa specifica viene registrata solo lato server.

Inizia dalla pagina della cronologia di autenticazione nella Claude Console. I tentativi di scambio recenti mostrano l'issuer e la regola che sono stati valutati, i claim JWT che sono stati ispezionati e quale passaggio di validazione è fallito, il che di solito rende superflui i controlli seguenti.

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

Modalità di origine JWKS

Quando registri un issuer di federazione, il campo jwks controlla come Anthropic ottiene le chiavi pubbliche utilizzate per verificare le firme JWT da quell'issuer. È una discriminated union con chiave su type:

`jwks.type`	Forma di `jwks`	Comportamento	Usa quando
`discovery` (predefinito)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` è opzionale; impostalo quando l'URL di discovery differisce da `issuer_url`)	Anthropic recupera `<discovery_base or issuer_url>/.well-known/openid-configuration`, legge `jwks_uri` dal documento di discovery e recupera il JWKS da lì.	Il tuo IdP serve un documento di discovery OIDC standard su internet pubblico. La maggior parte dei provider gestiti (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) lo supporta.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic recupera il JWKS direttamente da `url`. L' viene utilizzato solo per il confronto di stringhe con il claim del JWT e non viene mai contattato.

La discriminated union rende i campi complementari mutuamente esclusivi per costruzione. Sia discovery sia explicit_url accettano anche una stringa opzionale 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 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 un 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 questa disciplina autonomamente. 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.

Nella modalità inline non c'è alcun aggiornamento automatico delle chiavi. Quando il tuo identity provider ruota le sue chiavi di firma, devi aggiornare la configurazione dell'issuer con il nuovo JWKS, altrimenti tutti gli scambi di token falliranno la verifica della firma.

Was this page helpful?

AmministrazioneAutenticazione

Riferimento WIF

Variabili d'ambiente, regole di validazione, configurazione dei profili e riferimento agli errori per Workload Identity Federation.

Richiesta di scambio token

Campo	Obbligatorio	Descrizione
`grant_type`	Sì	Sempre `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Sì	Il JWT OIDC emesso dal tuo identity provider.
`federation_rule_id`	Sì	ID con tag (`fdrl_...`) della regola di federazione da valutare.
`organization_id`	Sì	UUID della tua organizzazione Anthropic.
`service_account_id`	Sì	ID con tag (`svac_...`) del service account di destinazione.
`workspace_id`	Condizionale	ID con tag (`wrkspc_...`) del workspace a cui limitare l'ambito del token emesso, oppure il valore letterale `default` per il workspace predefinito dell'organizzazione. Obbligatorio quando la regola è abilitata per più di un workspace. Se omesso, il server seleziona l'unico workspace abilitato della regola.

Risposta dello scambio token

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

Campo	Tipo	Descrizione
`access_token`	string	Il token Anthropic a breve durata, con prefisso `sk-ant-oat01-...`. Passalo come `Authorization: Bearer <token>`.
`token_type`	string	Sempre `Bearer`.
`expires_in`	integer	Secondi fino alla scadenza del token.
`scope`	string	Lo scope OAuth concesso dalla regola corrispondente.

Variabili d'ambiente

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

Variabile	Obbligatoria	Descrizione	Esempio
`ANTHROPIC_FEDERATION_RULE_ID`	Sì	ID con tag della regola di federazione da valutare.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Sì	UUID della tua organizzazione Anthropic. Lo trovi nella Claude Console in Settings > Organization.	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	Una tra `_TOKEN_FILE` o `_TOKEN`	Percorso del filesystem al JWT emesso dal tuo "identity provider" (provider di identità), o IdP. L'SDK rilegge questo file a ogni scambio in modo che i token proiettati che ruotano su disco siano sempre aggiornati.	`/var/run/secrets/anthropic.com/token`

Precedenza delle credenziali

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

Ordine	Sorgente	Note
1	Argomento del costruttore (`api_key=`, `auth_token=`, `credentials=`)	Sovrascrive sempre tutto il resto.
2	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN`	Oscura completamente la federazione. Rimuovi queste variabili quando migri dalle chiavi API.
3	`ANTHROPIC_PROFILE`	Carica `<config_dir>/configs/<name>.json`. Un profilo nominato mancante è un errore, non un passaggio alla sorgente successiva.
4	Variabili d'ambiente di federazione	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + + .

File di configurazione del profilo

Directory di configurazione

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

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

Profilo attivo

Il nome del profilo attivo viene risolto in questo ordine:

$ANTHROPIC_PROFILE
Il contenuto di <config_dir>/active_config (un file di una riga scritto da ant profile activate <name>)
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.

Layout dei file

Percorso	Contenuto	Sensibilità
`<config_dir>/configs/<profile>.json`	`version`, il blocco `authentication`, `organization_id`, `workspace_id` e `base_url`.	Non segreto. Sicuro da committare o includere in un'immagine.
`<config_dir>/credentials/<profile>.json`	`version`, l'`access_token` memorizzato nella cache, `expires_at` e (per il login interattivo) `refresh_token`.	Segreto. Scritto dall'SDK con modalità `0600`.

Esempio di profilo di federazione

configs/production.json

{
  "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 è 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 dell'API Claude può chiamare l'access token emesso.

Scope	Concede accesso a
`workspace:developer`	Tutti gli endpoint non amministrativi dell'API Claude nel workspace della regola: Messages (inclusi streaming e conteggio dei token), Models, Managed Agents e le loro sessioni, Files e Skills. Questo corrisponde all'accesso che ha una chiave API emessa per lo stesso workspace.
`org:manage_tunnels`	L'API dei tunnel MCP: elencare e ottenere tunnel, registrare e archiviare certificati CA, rivelare e ruotare il token del tunnel e archiviare tunnel. La finestra modale di creazione tunnel della Console blocca questo scope quando crei una regola da essa.

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.

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.

Campi delle risorse

Campo	Vincolo
`name` di issuer, regola e service account	Deve corrispondere a `^[a-z0-9-]+$`, lunghezza da 1 a 255 caratteri.
`workspace_id`	Opzionale. Il workspace (`wrkspc_...`) la cui quota, fatturazione e limiti di velocità si applicano ai token emessi sotto questa regola. Deve essere un workspace nella stessa organizzazione e il service account di destinazione deve essere membro di quel workspace. Può essere omesso per le regole configurate per un solo workspace.
`token_lifetime_seconds`	Intero tra `60` e `86400` (da 1 minuto a 24 ore). Predefinito `3600`. I valori al di fuori di questo intervallo vengono rifiutati al momento della richiesta. Consulta Durata e refresh del token.

Campi URL

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

Vincolo	Dettaglio
Schema	Deve essere `https`.
Porta	Deve essere `443` (esplicita o predefinita).
Host	Deve essere un nome host DNS pubblico per il tuo provider OIDC. Deve risolversi in indirizzi IP pubblici; i letterali IP non sono accettati.

Gli errori di validazione 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 JWT

Vincolo	Dettaglio
Dimensione massima	Il JWT `assertion` deve essere al massimo 16 KiB.
Algoritmo di firma	Sono accettati solo algoritmi asimmetrici (famiglie RSA ed ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) e `none` vengono rifiutati.
Key ID	L'header del JWT deve contenere un `kid` che corrisponda a una chiave nel JWKS dell'issuer. I token senza `kid` vengono rifiutati.
Claim obbligatori	`sub` deve essere presente. `iat` deve essere presente e non nel futuro. `exp` deve essere presente e nel futuro.
Durata massima	La durata del token ( meno ) non deve superare il massimo configurato dell'issuer (1 ora per impostazione predefinita, configurabile per ciascun issuer nella Claude Console).

Semantica di corrispondenza delle regole

Matcher	Tipo	Semantica
`subject_prefix`	string	Corrispondenza esatta con il claim `sub` del JWT. Un `` finale lo rende una corrispondenza per prefisso (il valore `sub` deve iniziare con i caratteri prima del ``). Case-sensitive.
`audience`	string	Il claim `aud` del JWT deve contenere esattamente questa stringa. Quando `aud` è un array, qualsiasi elemento che corrisponde esattamente soddisfa il controllo.
`claims`	map<string, string>	Ogni chiave è un nome di claim di primo livello e ogni valore è il valore stringa esatto richiesto. Per claim annidati, numerici, booleani o complessi come liste e mappe, usa invece `condition` con un'espressione CEL.

Ambiente di valutazione CEL

L'espressione condition ha accesso a una singola variabile:

Variabile	Tipo	Contenuto
`claims`	map	L'intero set di claim JWT decodificato. Gli oggetti annidati sono accessibili come mappe annidate.

Esempio:

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

Errori

Errori di scambio token

Stato	Errore	Causa	Risoluzione
400	`invalid_request`	`federation_rule_id` è malformato o manca un campo obbligatorio della richiesta.	Verifica l'ID `fdrl_` e che il corpo della richiesta includa tutti i campi obbligatori.
400	`invalid_request`	`workspace_id_required`: la regola di federazione è abilitata per più di un workspace e la richiesta omette `workspace_id`.	Imposta `ANTHROPIC_WORKSPACE_ID` (o il campo `workspace_id` nel corpo di una richiesta grezza) sull'ID `wrkspc_...` a cui vuoi limitare l'ambito del token. Consulta Richiesta di scambio token.
400

Tutti i fallimenti invalid_grant restituiscono HTTP 400; la causa specifica viene registrata solo lato server e non esposta nella risposta.

Fallimenti comuni lato SDK

Sintomo	Causa	Risoluzione
L'SDK segnala "no credentials" invece di eseguire lo scambio	Una tra `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` o `ANTHROPIC_IDENTITY_TOKEN[_FILE]` non è impostata e nessun profilo è attivo.	Imposta tutte e quattro le variabili, oppure configura un profilo.
L'SDK si autentica con una chiave API invece di federare	`ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` è impostata e vince la precedenza.	Rimuovi la variabile della chiave o del token.
`FileNotFoundError` alla prima richiesta	Il percorso in `ANTHROPIC_IDENTITY_TOKEN_FILE` non esiste. L'SDK apre il file in modo lazy al momento dello scambio.	Conferma che il volume del token proiettato sia montato e che il percorso corrisponda.
Lo scambio token ha successo ma una richiesta all'API Claude restituisce 403

Risolvere i problemi di uno scambio fallito

Una risposta 400 invalid_grant è intenzionalmente opaca; la causa specifica viene registrata solo lato server.

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

Modalità di origine JWKS

`jwks.type`	Forma di `jwks`	Comportamento	Usa quando
`discovery` (predefinito)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` è opzionale; impostalo quando l'URL di discovery differisce da `issuer_url`)	Anthropic recupera `<discovery_base or issuer_url>/.well-known/openid-configuration`, legge `jwks_uri` dal documento di discovery e recupera il JWKS da lì.	Il tuo IdP serve un documento di discovery OIDC standard su internet pubblico. La maggior parte dei provider gestiti (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) lo supporta.
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic recupera il JWKS direttamente da `url`. L' viene utilizzato solo per il confronto di stringhe con il claim del JWT e non viene mai contattato.

Rotazione delle chiavi e caching

Was this page helpful?