SSO per Devin air-gapped con il tuo IdP

Questa documentazione riguarda le distribuzioni di Devin per il governo federale. Torna alla documentazione di Devin

Per impostazione predefinita, l’accesso alla build air-gapped è controllato solo dal file di licenza. 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=<path>`

Il file specifica una sola modalità. Se il file non esiste, il prodotto si comporta come se contenesse "mode": "license".

/etc/devin/auth.json

{
  "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 `<issuer>/.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.

I campi sconosciuti vengono rifiutati. In modalità license sono consentiti solo schema_version e mode.

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.

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:

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.
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:<port>/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.
Se vuoi usare required_group, l’ID token deve contenere la claim di appartenenza ai gruppi indicata in groups_claim (groups per impostazione predefinita).
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.

Accedi da un terminale sulla workstation:

devin auth login

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.

devin auth login --force-manual-token-flow

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

devin auth status

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 (<reason>) seguito da Run \devin auth login` to sign in.`

devin auth logout

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:

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:

"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 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.

​Crea il file di autenticazione

​Registra il client presso il tuo IdP

​Accesso

​Verificare lo stato ed effettuare il logout

​Cosa convalida la CLI

​Gli endpoint rilevati devono trovarsi sullo stesso host dell’emittente

​Come si propaga la revoca

​Riconvalida nelle sessioni in esecuzione

​Cosa viene sottoposto ad audit

​Codici di errore IDP

Crea il file di autenticazione

Registra il client presso il tuo IdP

Accesso

Verificare lo stato ed effettuare il logout

Cosa convalida la CLI

Gli endpoint rilevati devono trovarsi sullo stesso host dell’emittente

Come si propaga la revoca

Riconvalida nelle sessioni in esecuzione

Cosa viene sottoposto ad audit

Codici di errore IDP