> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # SSO per Devin air-gapped con il tuo IdP > Richiedi l'accesso a Devin Desktop e alla CLI air-gapped tramite il tuo provider di identità OIDC: file di autenticazione, impostazioni del client, accesso basato sui gruppi, eventi di audit, codici IDP. > [!NOTE] > > Questa documentazione riguarda le distribuzioni di Devin per il governo federale. [Torna alla documentazione di Devin](/it/get-started/devin-intro) Per impostazione predefinita, l'accesso alla build air-gapped è controllato solo dal [file di licenza](/it/federal/air-gapped/license). Puoi inoltre richiedere a ogni utente di autenticarsi tramite **il tuo provider di identità OIDC**. L'SSO (Single Sign-On) costituisce un livello aggiuntivo rispetto alla licenza: la licenza resta obbligatoria e il flusso di accesso viene eseguito sull'emittente da te configurato. ## Crea il file di autenticazione | | | | - | - | | Percorso predefinito | `/etc/devin/auth.json` | | Percorso predefinito (Windows) | `C:\ProgramData\Devin\auth.json` | | Override | `DEVIN_AUTH_FILE=` | Il file specifica una sola modalità. Se il file non esiste, il prodotto si comporta come se contenesse `"mode": "license"`. ```json /etc/devin/auth.json theme={null} { "schema_version": 0, "mode": "sso", "issuer": "https://sso.example.com", "client_id": "devin-cli", "scopes": ["openid", "profile", "email"], "groups_claim": "groups", "required_group": "devin-users", "additional_endpoint_hosts": [] } ``` | Campo | Obbligatorio | Significato | | - | - | - | | `schema_version` | sì | Deve essere `0`. | | `mode` | sì | `"sso"` per richiedere il login, oppure `"license"` per l'accesso con sola licenza (valore predefinito se il file non esiste). | | `issuer` | sì (sso) | L'URL dell'emittente OIDC. Deve usare `https://` (`http://` è accettato solo per host di loopback) e non deve contenere stringa di query, frammento o credenziali incorporate. Il rilevamento viene eseguito su `/.well-known/openid-configuration`. | | `client_id` | sì (sso) | Il client che registri presso l'IdP. | | `scopes` | no | Il valore predefinito è `openid profile email`. Se impostato, deve includere `openid`. `offline_access` viene richiesto automaticamente se l'IdP lo supporta, in modo da ottenere un token di aggiornamento. | | `groups_claim` | no | Claim dell'ID token che contiene l'appartenenza ai gruppi. Il valore predefinito è `groups`. | | `required_group` | no | Se impostato, il login viene rifiutato a meno che questo valore non compaia nel claim dei gruppi. | | `additional_endpoint_hosts` | no | Host aggiuntivi su cui il documento di rilevamento dell'IdP può esporre endpoint. Lascialo vuoto se non ti serve; vedi [Gli endpoint rilevati devono restare sull'emittente](#discovered-endpoints-must-stay-on-the-issuer). | I campi sconosciuti vengono rifiutati. In modalità `license` sono consentiti solo `schema_version` e `mode`. > [!TIP] > > Se il tuo IdP usa un certificato emesso da una CA privata, imposta `DEVIN_CA_BUNDLE` su un bundle PEM affinché la CLI lo consideri attendibile; vedi [Rete e certificati](/it/federal/air-gapped/network-and-certificates). ## Registra il client presso il tuo IdP La CLI esegue il **flusso authorization-code OIDC con PKCE (S256)** come **client pubblico**; non è previsto alcun segreto client. Il client che registri deve soddisfare i seguenti requisiti: 1. Deve essere un client **pubblico** (senza segreto client) con l'ID indicato in `client_id`, ad esempio `devin-cli`, con la concessione authorization-code abilitata e il metodo PKCE `S256`. 2. `http://127.0.0.1/callback` deve essere registrato come URI di reindirizzamento valido. La CLI resta in ascolto su una porta di loopback casuale (`http://127.0.0.1:/callback`) per il flusso tramite browser e usa l'indirizzo fisso `http://127.0.0.1/callback` per il flusso manuale. Secondo la RFC 8252, l'IdP dovrebbe ignorare la porta di loopback; se il tuo non lo fa, registra un carattere jolly corrispondente. 3. Se vuoi usare `required_group`, l'ID token deve contenere la claim di appartenenza ai gruppi indicata in `groups_claim` (`groups` per impostazione predefinita). 4. L'IdP deve restituire un ID token al momento del refresh (la maggior parte lo fa quando viene concesso l'ambito `openid`) e la durata dell'ID token per questo client deve essere breve. Per il motivo, consulta [Come si propaga la revoca](#how-revocation-propagates). ## Accesso Accedi da un terminale sulla workstation: ```sh theme={null} devin auth login ``` ```text theme={null} Opening your browser to sign in with your identity provider... If the browser does not open, visit: https://sso.example.com/authorize?client_id=devin-cli&... (Use `devin auth login --force-manual-token-flow` on headless machines.) Logged in as jsmith via https://sso.example.com. Token expires at 2026-03-02 15:04:05 UTC. ``` Su un host headless o tramite SSH, usa il flusso manuale. La CLI mostra un URL da aprire in un browser su qualsiasi macchina; dopo l'accesso, il browser viene reindirizzato a un URL `127.0.0.1` che non si caricherà. Copia l'URL completo (inclusi i parametri di query) e incollalo nel terminale. ```sh theme={null} devin auth login --force-manual-token-flow ``` ```text theme={null} Open this URL in a browser (on any machine) and sign in: https://sso.example.com/authorize?client_id=devin-cli&... After signing in, the browser is redirected to a 127.0.0.1 URL that will not load — copy that full URL (including its query parameters) and paste it here. Paste the full redirect URL: ``` Devin Desktop usa le stesse credenziali di accesso tramite l'agente incluso nel bundle; se l'utente non ha effettuato l'accesso, gli viene chiesto di accedere dalle impostazioni di Devin prima di iniziare a lavorare. ## Verificare lo stato ed effettuare il logout ```sh theme={null} devin auth status ``` ```text theme={null} Auth mode: SSO (issuer: https://sso.example.com) Status: logged in User: jsmith Subject: 6f1c2a0e-... Groups: devin-users Token expires at 2026-03-02 15:04:05 UTC. ``` Se l'accesso memorizzato nella cache non è presente o non può più essere rinnovato, l'output è `Status: not logged in ()` seguito da `Run \`devin auth login\` to sign in.\` ```sh theme={null} devin auth logout ``` ```text theme={null} Logged out: local SSO tokens deleted. ``` Il logout avviene solo in locale: elimina la cache dei token senza contattare l'IdP. ## Cosa convalida la CLI L'ID token viene convalidato localmente: firma rispetto al JWKS dell'IdP, `iss`, `aud`, scadenza (con una tolleranza di 120 secondi per lo sfasamento dell'orologio), il `nonce` di login e il controllo di appartenenza al gruppo. L'ID token e il token di aggiornamento vengono memorizzati nell'archivio locale delle credenziali con autorizzazioni riservate al solo proprietario (`0600`) e aggiornati in background tramite l'IdP. Quando l'SSO è configurato e non esiste un login valido (e l'aggiornamento in background non riesce), la CLI si chiude all'avvio con un errore che invita l'utente a eseguire `devin auth login`. La CLI non segue mai i reindirizzamenti HTTP provenienti dall'IdP: una risposta `3xx` dall'endpoint di rilevamento, JWKS o token fa fallire il login con un errore che indica l'endpoint interessato, quindi `issuer` deve puntare agli URL effettivamente esposti dall'IdP. ### Gli endpoint rilevati devono trovarsi sullo stesso host dell'emittente I valori `authorization_endpoint`, `token_endpoint` e `jwks_uri` ottenuti tramite il rilevamento devono avere **lo stesso schema, host e porta** di `issuer` (le porte predefinite sono considerate equivalenti). Un endpoint su qualsiasi altro host viene rifiutato e il login non riesce, con un errore simile al seguente: ```text theme={null} IdP discovery document advertises jwks_uri 'https://keycloak.corp.internal:8443/realms/devin/protocol/openid-connect/certs' on host 'keycloak.corp.internal:8443', which is not the configured issuer's host 'sso.corp.example:443'; refusing to trust it. If this IdP really serves that endpoint from a different host, add "keycloak.corp.internal" to `sso.additional_endpoint_hosts` in the auth file ``` Alcune topologie di IdP espongono legittimamente gli endpoint da più di un host. Il caso più comune negli ambienti on-premise è Keycloak con `hostname-backchannel-dynamic=true`, in cui `token_endpoint` e `jwks_uri` vengono riscritti con l'hostname interno tramite il quale la CLI si è connessa. Se, e solo se, hai verificato nella configurazione dell'IdP stesso che l'host aggiuntivo è voluto, aggiungilo: ```json theme={null} "additional_endpoint_hosts": ["keycloak.corp.internal"] ``` Le voci sono nel formato `host` (qualsiasi porta) o `host:port` e il confronto non distingue tra maiuscole e minuscole. Non sono supportati caratteri jolly e non è possibile disattivare la verifica. L'elenco di elementi consentiti non allenta mai i requisiti TLS: un endpoint `http://` viene comunque rifiutato se l'emittente è `https://`. Non aggiungere un host solo perché compare in un errore di accesso: l'errore indica proprio che la verifica sta funzionando. ## Come si propaga la revoca Il controllo di appartenenza al gruppo viene valutato sull'ID token memorizzato nella cache: la rimozione di un utente da `required_group` (o la sua disattivazione) nell'IdP diventa quindi effettiva al successivo aggiornamento del token, ovvero al più tardi alla scadenza dell'ID token attuale, più i 120 secondi di tolleranza per lo sfasamento dell'orologio. Se è importante che la revoca sia rapida, imposta una durata breve per l'ID token di questo client. Se una risposta di aggiornamento non include un nuovo ID token, si continua a usare l'ID token memorizzato nella cache, ma non oltre 24 ore dopo il valore `exp` di quel token; trascorso tale periodo, l'utente deve accedere di nuovo anche se l'IdP accetta ancora il token di aggiornamento. ### Riconvalida nelle sessioni in esecuzione Mentre Devin Desktop (o qualsiasi client dell'agente incluso nel bundle) è in esecuzione, l'agente verifica nuovamente l'accesso ogni **60 secondi** e forza un aggiornamento del token presso l'IdP almeno ogni **15 minuti**. Se una verifica non va a buon fine, l'agente registra un evento di audit `sso_revalidation_failed` con il codice `IDP`, smette di accettare nuove attività e si arresta; l'utente deve accedere di nuovo e riavviarlo. ## Cosa viene sottoposto ad audit L'attività SSO viene scritta nel [registro di audit](/it/federal/air-gapped/on-disk-formats#audit-log) locale sotto forma di eventi `auth`. Ogni evento per cui è disponibile un token convalidato riporta l'identità SSO in `actor` (`sso_issuer`, `sso_subject`, `sso_user`, `sso_groups`). | `action` | Quando | | - | - | | `sso_login` | Accesso completato (`devin auth login` o Desktop). | | `sso_login_denied` | Accesso rifiutato dopo la risposta dell'IdP: manca il gruppo obbligatorio (`error_code: "IDP004"`), oppure l'ID token restituito non ha superato la convalida o è assente (`IDP005`). `actor` riporta l'identità attestata dall'IdP; nulla viene memorizzato nella cache. | | `sso_refresh` | Token aggiornati presso l'IdP. | | `sso_logout` | `devin auth logout` o disconnessione da Desktop. | | `sso_revalidation_failed` | Un agente in esecuzione ha perso l'accesso e si sta arrestando; `error_code` riporta il codice `IDP`. | ## Codici di errore IDP | Codice | Significato | Cosa fare | | - | - | - | | `IDP001` | Il file di autenticazione è illeggibile o non valido. | Correggi `/etc/devin/auth.json` (o il percorso indicato in `DEVIN_AUTH_FILE`); il messaggio indica il campo che causa l'errore. | | `IDP002` | Nessun login memorizzato nella cache per l'emittente configurato. | Esegui `devin auth login`. | | `IDP003` | Il login non è valido o è scaduto e non è stato possibile rinnovarlo automaticamente (anche in caso di risposta `invalid_grant` dall'IdP). | Esegui di nuovo `devin auth login`. | | `IDP004` | L'accesso è stato effettuato, ma l'utente non è membro di `required_group`. | Aggiungi l'utente al gruppo nell'IdP oppure correggi `required_group` / `groups_claim`. | | `IDP005` | L'IdP non è raggiungibile oppure ha restituito un errore. | Verifica la raggiungibilità di rete, l'attendibilità TLS (`DEVIN_CA_BUNDLE`) e i log dell'IdP. | | `IDP006` | La cache locale dei token SSO è illeggibile, malformata o non riservata all'utente attuale. | Esegui `devin auth login`: un nuovo login riscrive la cache. | Il catalogo completo è disponibile nella pagina [Codici di errore](/it/federal/air-gapped/error-codes). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.