--- title: Riferimento WIF url: https://platform.claude.com/docs/it/manage-claude/wif-reference description: Variabili d'ambiente, regole di convalida, configurazione dei profili e riferimento agli errori per Workload Identity Federation. --- Questa pagina raccoglie le superfici di configurazione, i vincoli di convalida e le mappature degli errori per [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation). Per le procedure guidate di configurazione, consulta le [guide dei provider](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation#identity-providers). ## Richiesta di scambio del token `POST /v1/oauth/token` accetta un corpo JSON che utilizza il grant `jwt-bearer` di [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). L'SDK costruisce questa richiesta per te a partire dalle [variabili d'ambiente](https://platform.claude.com/docs/it/manage-claude/wif-reference#environment-variables); gli esempi cURL in ciascuna guida dei 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 provider di identità. | | `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_...`) dell'account di servizio di destinazione. | | `workspace_id` | Condizionale | ID con tag (`wrkspc_...`) del workspace a cui limitare l'ambito del token emesso. Obbligatorio quando la regola è abilitata per più di un workspace. Se omesso, il server seleziona l'unico workspace abilitato della regola. Anche il valore letterale `default` funziona per il Default Workspace dell'organizzazione, ma è deprecato; usa l'ID `wrkspc_...` di quel workspace. | ## Risposta dello scambio del token `POST /v1/oauth/token` restituisce una risposta token OAuth 2.0 standard ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-5.1)): | Campo | Tipo | Descrizione | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `access_token` | string | Il token Anthropic di breve durata, con prefisso `sk-ant-oat01-...`. Passalo come `Authorization: Bearer `. | | `token_type` | string | Sempre `Bearer`. | | `expires_in` | integer | Secondi mancanti alla scadenza del token. | | `scope` | string | L'ambito 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 pagina [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) nella Claude Console. | `00000000-0000-0000-0000-000000000000` | | `ANTHROPIC_IDENTITY_TOKEN_FILE` | Una tra `_TOKEN_FILE` o `_TOKEN` | Percorso nel filesystem del 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` | | `ANTHROPIC_IDENTITY_TOKEN` | Una tra `_TOKEN_FILE` o `_TOKEN` | Il JWT letterale come stringa. Usala quando la tua piattaforma inietta il token come variabile d'ambiente anziché come file. | `eyJhbGciOiJSUzI1NiIs...` | | `ANTHROPIC_SERVICE_ACCOUNT_ID` | Sì | ID con tag dell'account di servizio Anthropic di destinazione per conto del quale agisce il token di accesso emesso. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Condizionale | ID con tag del workspace a cui limitare l'ambito del token emesso. Obbligatoria quando la regola di federazione è abilitata per più di un workspace; facoltativa quando la regola è associata a un singolo workspace. Il token emesso è limitato a questo workspace al momento dello scambio, quindi cambiare workspace richiede un nuovo scambio. Anche il valore letterale `default` funziona per il Default Workspace, ma è deprecato; usa il suo ID `wrkspc_...`. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | No | Nome di un [profilo di configurazione](https://platform.claude.com/docs/it/manage-claude/wif-reference#profile-configuration-file) da caricare. Ha la precedenza sulle variabili d'ambiente di federazione in questa tabella. | `staging-profile` | 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. Una variabile impostata su una stringa vuota può comunque occupare la propria posizione nella catena di precedenza delle credenziali. Rimuovi le variabili di credenziali inutilizzate anziché svuotarle. ### Precedenza delle credenziali L'SDK risolve le credenziali in questo ordine. Vince la prima fonte che fornisce una credenziale. | Ordine | Fonte | Note | | ------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | Argomento del costruttore (`api_key=`, `auth_token=`, `credentials=`) | Ha sempre la precedenza su tutto il resto. | | 2 | `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` | Oscura completamente la federazione. Rimuovile quando esegui la migrazione dalle chiavi API. | | 3 | `ANTHROPIC_PROFILE` | Carica `/configs/.json`. Un profilo con nome mancante è un errore, non un passaggio alla fonte successiva. | | 4 | Variabili d'ambiente di federazione | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`. | | 5 | Profilo attivo | Risolto da `/active_config`, con fallback a un profilo denominato `default`. | Nella CLI `ant`, le impostazioni per [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) 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 `/active_config` (un file di una riga scritto da `ant profile activate `) 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 | Percorso | Contenuto | Sensibilità | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `/configs/.json` | `version`, il blocco `authentication`, `organization_id`, `workspace_id` e `base_url`. | Non segreto. Può essere sottoposto a commit o incluso in un'immagine in sicurezza. | | `/credentials/.json` | `version`, l'`access_token` memorizzato nella cache, `expires_at` e (per l'accesso 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 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 ```json 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` 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. | Ambito | Concede l'accesso a | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Tutti gli endpoint non amministrativi della Claude API nel workspace della regola: [Messages](https://platform.claude.com/docs/it/api/messages) (inclusi streaming e conteggio dei token), [Models](https://platform.claude.com/docs/it/api/models/list), [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview) e le relative sessioni, [Files](https://platform.claude.com/docs/it/build-with-claude/files) e [Skills](https://platform.claude.com/docs/it/build-with-claude/skills-guide). Corrisponde all'accesso di cui dispone una chiave API di workspace nello stesso workspace. | | `workspace:inference` | Gli endpoint di inferenza nel workspace della regola: [Messages](https://platform.claude.com/docs/it/api/messages) (inclusi streaming e conteggio dei token), [Models](https://platform.claude.com/docs/it/api/models/list) e l'[endpoint di chat compatibile con OpenAI](https://platform.claude.com/docs/it/cli-sdks-libraries/libraries/openai-sdk). Usalo per carichi di lavoro che devono solo chiamare Claude e non devono mai gestire Files, Skills o altre risorse. | | `workspace:manage_tunnels` | L'[API dei tunnel MCP](https://platform.claude.com/docs/it/agents-and-tools/mcp-tunnels/reference#tunnels-api): creare, elencare e ottenere tunnel, registrare e archiviare certificati CA, rivelare e ruotare il token del tunnel e archiviare tunnel. La finestra modale di creazione del tunnel della Console blocca questo ambito quando crei una regola da essa. | | `org:admin` | Accesso completo all'[Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api) (membri dell'organizzazione, inviti, workspace, chiavi API e il resto). Un token OAuth `org:admin` può creare o modificare solo regole con ambito `workspace:developer` o `workspace:inference` e non può aggiornare un issuer che supporta una regola con qualsiasi altro ambito; consulta i [vincoli](https://platform.claude.com/docs/it/manage-claude/wif-admin-api#permissions-and-constraints). | 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. | `oauth_scope` della regola | `organization_role` dell'account di servizio | Permessi effettivi | | -------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Accesso alla Claude API solo nel workspace della regola. L'ambito limita il token al di sotto del ruolo. | | `org:admin` | `admin` | Accesso completo all'Admin API (membri dell'organizzazione, inviti, workspace, chiavi API e il resto), escluse le eccezioni per i chiamanti OAuth; consulta i [vincoli](https://platform.claude.com/docs/it/manage-claude/wif-admin-api#permissions-and-constraints). | ## 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](https://platform.claude.com/docs/it/api/organization/service_accounts), il [riferimento API degli issuer di federazione](https://platform.claude.com/docs/it/api/organization/federation/issuers) e il [riferimento API delle regole di federazione](https://platform.claude.com/docs/it/api/organization/federation/rules). ### Campi delle risorse | Campo | Vincolo | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` di issuer, regola e account di servizio | Deve corrispondere a `^[a-z0-9-]+$`, lunghezza da 1 a 255 caratteri. | | `workspace_id` | Obbligatorio alla creazione a meno che `applies_to_all_workspaces` sia true. Il workspace (`wrkspc_...`) la cui quota, fatturazione e limiti di velocità si applicano ai token emessi in base a questa regola. Deve essere un workspace della stessa organizzazione e l'account di servizio di destinazione deve essere membro di quel workspace. | | `applies_to_all_workspaces` | Booleano. Imposta `true` per abilitare la regola in ogni workspace dell'organizzazione anziché indicarne uno; alla creazione è obbligatorio questo campo oppure `workspace_id`. | | `token_lifetime_seconds` | Intero compreso tra `60` e `86400` (da 1 minuto a 24 ore). Valore predefinito `3600`. I valori al di fuori di questo intervallo vengono rifiutati al momento della richiesta. Consulta [Durata e aggiornamento del token](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation#token-lifetime-and-refresh). | ### Campi URL I campi `issuer_url`, `jwks.discovery_base` e `jwks.url` vengono convalidati: | 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; gli indirizzi IP letterali non sono accettati. | 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`). I vincoli sugli 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 nome host interno o a una porta non standard. ### Verifica del JWT | Vincolo | Dettaglio | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dimensione massima | Il JWT `assertion` deve essere al massimo di 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. | | ID della chiave | L'intestazione 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. | | Uso singolo | Un'asserzione che contiene un claim `jti` può essere scambiata una sola volta per issuer: ripetere uno scambio con lo stesso `jti` viene rifiutato come replay. Il campo `check_jti` dell'issuer (abilitato per impostazione predefinita) controlla questa verifica; le asserzioni senza claim `jti` non vi sono soggette. Consulta il [riferimento API degli issuer di federazione](https://platform.claude.com/docs/it/api/organization/federation/issuers). | | Durata massima | La durata del token (`exp` meno `iat`) non deve superare il massimo configurato per l'issuer (1 ora per impostazione predefinita, configurabile per ciascun issuer nella Claude Console). | | Sfasamento dell'orologio | Viene applicata una tolleranza di 30 secondi a `exp`, `nbf` e `iat`. | ## 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. | Matcher | Tipo | Semantica | | ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | Corrispondenza esatta con il claim `sub` del JWT. Un `*` finale lo rende una corrispondenza di prefisso (il valore di `sub` deve iniziare con i caratteri che precedono `*`). Distingue tra maiuscole e minuscole. | | `audience` | string | Il claim `aud` del JWT deve contenere esattamente questa stringa. Quando `aud` è un array, qualsiasi elemento che corrisponda esattamente soddisfa la verifica. | | `claims` | map\ | Ogni chiave è il nome di un 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. | | `condition` | string (CEL) | Un'espressione [CEL](https://cel.dev/) che deve restituire `true`. | ### Ambiente di valutazione CEL L'espressione `condition` ha accesso a una singola variabile: | Variabile | Tipo | Contenuto | | --------- | ---- | ---------------------------------------------------------------------------------------------------------- | | `claims` | map | L'intero insieme di claim del JWT decodificato. Gli oggetti annidati sono accessibili come mappe annidate. | Esempio: ```text wrap 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 restituisce `true` per più input del previsto concede un accesso più ampio del previsto. Preferisci i matcher statici quando esprimono il tuo vincolo. ## Errori ### Errori dello scambio del token `POST /v1/oauth/token` restituisce gli errori nel [formato di errore API](https://platform.claude.com/docs/it/api/errors) standard. L'SDK segnala un errore di scambio come `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), 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. | Stato | Errore | Causa | Risoluzione | | ----- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `federation_rule_id` non è formattato correttamente oppure manca un campo obbligatorio della richiesta. | Verifica l'ID `fdrl_` e che il corpo della richiesta includa tutti i campi obbligatori. | | 400 | `invalid_request_error` | `workspace_id` è presente ma non è un ID `wrkspc_...` ben formato né il valore letterale `default`. | Correggi il valore di `workspace_id`; il messaggio di risposta indica il formato previsto. | | 401 | `authentication_error` | Il claim `iss` del JWT non è esattamente uguale all'`issuer_url` registrato. | Confronta byte per byte, incluse barre finali e schema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | Il recupero del JWKS non è riuscito, il JWKS non è aggiornato oppure il JWT è stato firmato con una chiave non presente nel JWKS. | Per la modalità `inline`, aggiorna l'issuer con le chiavi ruotate. Per `discovery` ed `explicit_url`, verifica che l'endpoint JWKS sia raggiungibile sulla porta 443; se l'issuer ha ruotato di recente la propria chiave di firma, consulta [Rotazione delle chiavi e caching](https://platform.claude.com/docs/it/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | Il claim `exp` del JWT è nel passato (oltre la finestra di sfasamento di 30 secondi). | Verifica che il tuo provider di identità stia proiettando un token nuovo e che l'SDK stia rileggendo il file del token. | | 401 | `authentication_error` | Il JWT è stato verificato ma i suoi claim non soddisfano il blocco `match` della regola. | Decodifica il JWT e confronta ogni claim con la regola. `subject_prefix` distingue tra maiuscole e minuscole. `audience` richiede una corrispondenza esatta di un elemento. | | 401 | `authentication_error` | Il `federation_rule_id` non esiste, è archiviato oppure il JWT non è autorizzato per esso (consolidato per impedire l'enumerazione). | Verifica l'ID della regola nella Claude Console e che la regola non sia stata archiviata. | | 401 | `authentication_error` | La regola di federazione è abilitata per più di un workspace e la richiesta omette `workspace_id`. La voce della cronologia di autenticazione mostra il motivo `workspace_id_required`. | Imposta `ANTHROPIC_WORKSPACE_ID` (o il campo del corpo `workspace_id` in una richiesta grezza) sull'ID `wrkspc_...` a cui vuoi limitare l'ambito del token. Consulta [Richiesta di scambio del token](https://platform.claude.com/docs/it/manage-claude/wif-reference#token-exchange-request). | 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](https://platform.claude.com/settings/workload-identity-federation?tab=history) 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 | 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 usare la federazione | `ANTHROPIC_API_KEY` o `ANTHROPIC_AUTH_TOKEN` è impostata e ha 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 differito al momento dello scambio. | Verifica che il volume del token proiettato sia montato e che il percorso corrisponda. | | Lo scambio del token riesce ma una richiesta alla Claude API restituisce 403 | L'ambito del token emesso non concede l'accesso a quell'endpoint. | Confronta l'`oauth_scope` della regola con gli [ambiti OAuth](https://platform.claude.com/docs/it/manage-claude/wif-reference#oauth-scopes). | | L'autenticazione non riesce con una credenziale vuota | Una variabile d'ambiente di credenziali è esportata ma impostata su una stringa vuota. I valori vuoti possono comunque vincere la propria posizione di precedenza. | Rimuovi la variabile con `unset VAR` anziché `VAR=""`. | ## 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. Inizia dalla [pagina della cronologia di autenticazione](https://platform.claude.com/settings/workload-identity-federation?tab=history) nella Claude Console. I tentativi di scambio recenti mostrano l'issuer e la regola valutati, i claim del JWT esaminati e quale passaggio di convalida non è riuscito, il che di solito rende superflue le verifiche seguenti. Un errore opaco comune è un'asserzione riutilizzata: un'asserzione che contiene un claim `jti` può essere [scambiata una sola volta](https://platform.claude.com/docs/it/manage-claude/wif-reference#jwt-verification), 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: Decodifica l'asserzione che hai inviato in modo da poter confrontare ogni claim con la configurazione dell'issuer e della regola: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` 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. Il claim `aud` decodificato deve contenere il valore `audience` della regola come corrispondenza esatta. Quando `aud` è un array, un elemento deve corrispondere esattamente. 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. `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. Per la modalità `discovery`, recupera `/.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](https://platform.claude.com/docs/it/manage-claude/wif-reference#key-rotation-and-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`: | `jwks.type` | Forma di `jwks` | Comportamento | Quando usarla | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `discovery` (predefinita) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` è facoltativo; impostalo quando l'URL di discovery è diverso da `issuer_url`) | Anthropic recupera `/.well-known/openid-configuration`, legge `jwks_uri` dal documento di discovery e recupera il JWKS da lì. | Il tuo IdP fornisce 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'`issuer_url` viene usato solo per il confronto di stringhe con il claim `iss` del JWT e non viene mai contattato. | Il tuo IdP non fornisce un documento di discovery, oppure la discovery è solo interna ma il JWKS è raggiungibile pubblicamente. | | `inline` | `{ "type": "inline", "keys": [...] }` | Fornisci l'array di oggetti JWK inline (l'array `keys` del documento JWKS, non l'oggetto contenitore). Anthropic non effettua alcuna richiesta in uscita. L'`issuer_url` viene usato solo per il confronto con `iss`. | Ambienti air-gapped, cluster Kubernetes autogestiti con URL dell'issuer interni al cluster, oppure quando vuoi un controllo esplicito sulla rotazione delle chiavi. | 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. Nella modalità `inline` non esiste un aggiornamento automatico delle chiavi. Quando il tuo provider di identità ruota le proprie chiavi di firma, devi aggiornare la configurazione dell'issuer con il nuovo JWKS, altrimenti tutti gli scambi di token non supereranno la verifica della firma.