--- title: Riferimento WIF url: https://platform.claude.com/docs/it/manage-claude/wif-reference description: 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](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation). Per le procedure 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 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 generato. 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 di 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 prima della 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 del service account 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 generato. Obbligatoria quando la regola di federazione è abilitata per più di un workspace; facoltativa quando la regola è associata a un singolo workspace. L'ambito del token generato viene 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 di 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 ad esse 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=""` viene esportata, l'SDK seleziona il percorso della chiave API con una chiave vuota anziché passare alla federazione. Annulla l'impostazione delle variabili di credenziali inutilizzate anziché svuotarle. ### Precedenza delle credenziali L'SDK risolve le credenziali in questo ordine. La prima sorgente che fornisce 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. Annulla l'impostazione di queste variabili quando migri dalle chiavi API. | | 3 | `ANTHROPIC_PROFILE` | Carica `/configs/.json`. Un profilo nominato mancante è un errore, non un passaggio al successivo. | | 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 chiamato `default`. | 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 `/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 questo stesso ordine di risoluzione, quindi un profilo di federazione configurato qui autentica anche quegli 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. Sicuro da committare o incorporare in un'immagine. | | `/credentials/.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 più vecchi; omettilo quando scrivi una configurazione a mano e l'SDK tratta il file come la 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` che imposti su una regola di federazione determina quali endpoint dell'API Claude il token di accesso generato può chiamare. | Ambito | Concede accesso a | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Tutti gli endpoint non amministrativi dell'API Claude nel workspace della regola: [Messages](https://platform.claude.com/docs/it/api/messages) (incluso 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 loro 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 che ha una chiave API del workspace nello stesso workspace. | | `workspace:inference` | Gli endpoint di inferenza nel workspace della regola: [Messages](https://platform.claude.com/docs/it/api/messages) (incluso 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 i carichi di lavoro che devono solo chiamare Claude e non hanno mai bisogno di 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 i 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 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. | `oauth_scope` della regola | `organization_role` del service account | Permessi effettivi | | -------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Accesso all'API Claude 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), meno le esclusioni per il chiamante OAuth; consulta i [vincoli](https://platform.claude.com/docs/it/manage-claude/wif-admin-api#permissions-and-constraints). | ## 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](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 service account | 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 generati sotto questa regola. Deve essere un workspace nella stessa organizzazione, e il service account 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é nominarne uno; alla creazione è richiesto questo oppure `workspace_id`. | | `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 rinnovo 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 validati: | Vincolo | Dettaglio | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Schema | Deve essere `https`. | | Porta | Deve essere `443` (esplicita o predefinita). | | Host | Deve essere un hostname DNS pubblico per il tuo provider OIDC. Deve risolversi in indirizzi IP pubblici; i letterali IP non sono accettati. | 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`). 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 hostname 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'assertion che contiene un claim `jti` può essere scambiata una sola volta per issuer: la ripetizione di uno scambio con lo stesso `jti` viene rifiutata come replay. Il campo `check_jti` dell'issuer (abilitato per impostazione predefinita) controlla questa verifica; le assertion 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). | | Scostamento 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 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. | 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 dell'`*`). Sensibile alle maiuscole. | | `audience` | string | Il claim `aud` del JWT deve contenere questa stringa esatta. Quando `aud` è un array, qualsiasi elemento che corrisponde esattamente soddisfa la verifica. | | `claims` | map\ | 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. | | `condition` | string (CEL) | Un'espressione [CEL](https://cel.dev/) che deve valutare a `true`. | ### Ambiente di valutazione CEL L'espressione `condition` ha accesso a una singola variabile: | Variabile | Tipo | Contenuto | | --------- | ---- | ------------------------------------------------------------------------------------------------------------- | | `claims` | map | L'insieme completo dei claim decodificati del JWT. 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 limiti 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 del token `POST /v1/oauth/token` restituisce gli errori nel [formato di errore dell'API](https://platform.claude.com/docs/it/api/errors) standard. L'SDK racchiude gli errori di scambio in un `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `*config.FederationExchangeError`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`) tipizzato che espone lo stato HTTP, il corpo della risposta e il `request_id`. | Stato | Errore | Causa | Risoluzione | | ----- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | `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_error` | `workspace_id` è presente ma non è un ID `wrkspc_...` ben formato o il letterale `default`. | Correggi il valore `workspace_id`; il messaggio di risposta indica il formato atteso. | | 401 | `authentication_error` | Il claim `iss` del JWT non è esattamente uguale all'`issuer_url` registrato. | Confronta byte per byte, incluse le barre finali e lo schema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | Il recupero del JWKS è fallito, il JWKS è obsoleto, o 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`, conferma che l'endpoint JWKS sia raggiungibile sulla porta 443; se l'issuer ha recentemente ruotato la sua chiave di firma, consulta [Rotazione e caching delle chiavi](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 scostamento di 30 secondi). | Conferma che il tuo identity provider stia proiettando un token aggiornato 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` è sensibile alle maiuscole. `audience` richiede una corrispondenza esatta di un elemento. | | 401 | `authentication_error` | Il `federation_rule_id` non esiste, è archiviato, o il JWT non è autorizzato per esso (consolidato per prevenire l'enumerazione). | Conferma 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` su 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 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](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. ### Fallimenti comuni lato SDK | Sintomo | Causa | Risoluzione | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | L'SDK segnala "no credentials" invece di effettuare 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, o 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. | Annulla l'impostazione della 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 del token riesce ma una richiesta all'API Claude restituisce 403 | L'ambito del token generato non concede accesso a quell'endpoint. | Verifica l'`oauth_scope` della regola rispetto agli [Ambiti OAuth](https://platform.claude.com/docs/it/manage-claude/wif-reference#oauth-scopes). | | L'autenticazione fallisce con credenziale vuota | Una variabile d'ambiente di credenziale è esportata ma impostata su una stringa vuota. I valori vuoti vincono comunque il loro posto di precedenza. | Annulla l'impostazione della variabile con `unset VAR` anziché `VAR=""`. | ## 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. 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 che sono stati valutati, i claim del JWT che sono stati ispezionati e quale passaggio di validazione è fallito, il che di solito abbrevia le verifiche seguenti. Un fallimento opaco comune è un'assertion riutilizzata: un'assertion che contiene un claim `jti` può essere [scambiata solo una volta](https://platform.claude.com/docs/it/manage-claude/wif-reference#jwt-verification), 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: Decodifica l'assertion che hai inviato in modo da poter confrontare ogni claim con la configurazione del tuo issuer e della tua regola: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` 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. 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 (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. `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. Per la modalità `discovery`, recupera `/.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](https://platform.claude.com/docs/it/manage-claude/wif-reference#key-rotation-and-caching). ## 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`: | `jwks.type` | Forma di `jwks` | Comportamento | Usa quando | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discovery` (predefinito) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` è facoltativo; impostalo quando l'URL di discovery differisce 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 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'`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 serve un documento di discovery, o la discovery è solo interna ma il JWKS è raggiungibile pubblicamente. | | `inline` | `{ "type": "inline", "keys": [...] }` | Fornisci l'array di oggetti JWK inline (l'array `keys` dal documento JWKS, non l'oggetto wrapper). Anthropic non effettua alcuna richiesta in uscita. L'`issuer_url` viene usato solo per il confronto di `iss`. | Ambienti air-gapped, cluster Kubernetes autogestiti con URL di issuer interni al cluster, o 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 `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. 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.