Single sign-on

Vaultisse permette alle persone di accedere con un account che hanno già nella tua organizzazione, tramite OpenID Connect (OIDC). Funziona con Authentik, Keycloak, Authelia e qualsiasi altro provider che parli OIDC. Gli esempi qui sotto usano Authentik.

L'accesso con password continua a funzionare accanto all'SSO, a meno che tu non attivi la modalità solo SSO. Quando l'SSO è attivo, la pagina di accesso mostra un pulsante in più:

Come si comporta

• La prima volta che qualcuno accede con l'SSO, Vaultisse crea per lui un account, con la sua biblioteca e senza passaggio di approvazione. Entra chiunque il provider di identità lasci entrare, quindi controlla l'accesso lì. REGISTRATION_REQUIRES_APPROVAL e REGISTRATION_ENABLED non si applicano all'SSO.
• Se una persona ha già un account con password con la stessa email, e il provider dice che quell'email è verificata, l'SSO si collega a quell'account, così mantiene una sola biblioteca. Un'email che il provider non ha verificato non viene mai usata per collegare account.
• Gli accessi SSO saltano la verifica in due passaggi propria di Vaultisse, perché il provider ha già fatto quel passaggio se lo richiedi.
• Il logout termina solo la sessione di Vaultisse. Non disconnette la persona dal provider.
• Ogni avvio dell'SSO chiede al provider di autenticare di nuovo (prompt=login), così un computer condiviso non riutilizza mai in silenzio la sessione della persona precedente.

1. Crea l'applicazione presso il provider

In Authentik, crea un'applicazione con un provider OAuth2/OpenID. I nomi dei menu cambiano tra le versioni; i valori che ti servono sono:

Impostazione	Valore
Tipo di client	Confidential
URI di reindirizzamento / callback	https://books.example.com/auth/oidc/callback, corrispondente esattamente
Ambiti (scopes)	openid, profile, email

Poi annota tre cose dal provider: il Client ID, il Client secret e l'indirizzo dell'emittente (issuer). In Authentik l'emittente ha questo aspetto: https://auth.example.com/application/o/vaultisse/, con la barra finale.

In Authentik, chi può aprire l'applicazione è chi può accedere a Vaultisse, quindi associala ai gruppi o agli utenti che vuoi.

2. Configura Vaultisse

Aggiungi questo a .env:

OIDC_ISSUER=https://auth.example.com/application/o/vaultisse/
OIDC_CLIENT_ID=<client id>
OIDC_CLIENT_SECRET=<client secret>
OIDC_REDIRECT_URI=https://books.example.com/auth/oidc/callback

OIDC_REDIRECT_URI deve essere identico a quello registrato presso il provider, carattere per carattere. Di proposito non viene ricavato dalla barra degli indirizzi. Applicalo:

docker compose up -d

Ricarica la pagina di accesso: il pulsante dovrebbe esserci. Per cambiarne il testo, imposta OIDC_BUTTON_LABEL. Se lavori dietro un proxy, serve TRUST_PROXY=true come sempre, vedi Reverse proxy e HTTPS.

3. Accesso alla biblioteca tramite gruppi (opzionale)

Beta: questa parte è nuova in 1.3.7-beta.1. Vedi Provare una beta.

Di base l'SSO decide solo chi può accedere. Poi ogni persona viene invitata a mano alle biblioteche condivise, vedi Condividere una biblioteca e ruoli.

Se le tue persone appartengono già a dei gruppi presso il provider, puoi lasciare che siano quei gruppi a decidere chi sta in quale biblioteca, e con quale ruolo. Non serve invitare nessuno uno per uno: se sei nel gruppo, sei nella biblioteca, e se esci dal gruppo, perdi l'accesso.

Sul server può servire impostare una sola cosa: il nome del campo che porta i gruppi. Per impostazione predefinita è groups, e Authentik lo include con l'ambito profile. Se il tuo provider usa un altro nome, imposta OIDC_GROUPS_CLAIM.

In ogni biblioteca, un amministratore elenca i gruppi che hanno accesso. Apri la finestra Gestisci della biblioteca, trova Aggiungi per gruppo SSO, aggiungi una riga per gruppo con il nome del gruppo esattamente come lo scrive il provider, scegli il ruolo e fai clic su Salva:

Gruppo SSO	Ruolo
family-users	Normal
library-admins	Admin

Come funziona, a ogni accesso con SSO:

• La persona viene aggiunta a ogni biblioteca in cui compare uno dei suoi gruppi, accettata subito, con il ruolo più alto tra i gruppi corrispondenti. Chi è sia in family-users sia in library-admins diventa amministratore.
• Ogni biblioteca decide per sé. Ognuna elenca i propri gruppi, quindi una persona entra solo nelle biblioteche a cui associ i suoi gruppi, e lo stesso gruppo può avere ruoli diversi in biblioteche diverse.
• Quando una persona non ha più alcun gruppo dell'elenco, viene rimossa da quella biblioteca al suo prossimo accesso. Finché non accede di nuovo non cambia nulla, perché i gruppi vengono letti all'accesso.
• Se ha ancora libri in prestito da quella biblioteca, non viene rimossa. Diventa Restricted: non può prendere nulla di nuovo in prestito, ma i suoi prestiti restano registrati e possono essere restituiti. Quando restituisce tutto e accede di nuovo senza gruppo, viene rimossa. Se riottiene un gruppo, riottiene il suo ruolo.
• Le persone aggiunte a mano non vengono mai rimosse dall'SSO, e nemmeno la biblioteca personale di nessuno. Se un amministratore sceglie un ruolo a mano per qualcuno aggiunto dall'SSO, anche quella persona diventa un membro manuale.
• Una biblioteca senza gruppi in elenco resta completamente manuale.
• Se il provider non invia alcun gruppo in un accesso (per esempio manca l'ambito profile), Vaultisse lascia intatto l'accesso di tutti per quell'accesso, così un provider configurato male non può svuotare le tue biblioteche.
• Una biblioteca mantiene sempre un amministratore, e un gruppo non può dare il ruolo Borrower in una biblioteca con i prestiti disattivati. Quando una modifica violerebbe una regola, viene saltata e scritta nel registro del server. L'accesso funziona comunque.

Se aggiorni dalla 1.3.6: OIDC_GROUP_ROLES e l'opzione In base ai gruppi SSO non esistono più. Cancella OIDC_GROUP_ROLES dal tuo .env (viene ignorato) ed elenca i tuoi gruppi in ogni biblioteca. I membri che seguivano i gruppi SSO diventano normali membri manuali.

4. Biblioteche personali (opzionale)

Per impostazione predefinita, una nuova persona che entra con SSO riceve una biblioteca propria al primo accesso, come qualsiasi nuovo account. Se vuoi che veda solo le biblioteche che le danno i suoi gruppi, disattivalo:

OIDC_PERSONAL_VAULT=false

Questo riguarda solo chi accede con SSO per la prima volta dopo la modifica. Gli account esistenti mantengono la loro biblioteca.

5. Modalità solo SSO (opzionale)

Perché il provider sia l'unica fonte di verità su chi entra, chiudi del tutto la porta della password:

SSO_ONLY=true

Con questa opzione attiva, l'accesso con password e la registrazione sono disattivati, e la pagina di accesso mostra solo il pulsante SSO. Viene ignorata se l'SSO non è configurato completamente, quindi un errore nei valori OIDC_ non può lasciare tutti fuori. Ricordati di conservare un modo per raggiungere tu stesso il provider prima di attivarla.

Risoluzione dei problemi

"Sign in with SSO" non compare. Uno dei quattro valori OIDC_ obbligatori è vuoto, oppure DEMO_MODE è attivo. Verifica con docker compose exec app env | grep OIDC_.

L'accesso torna alla pagina di login con un errore. Il messaggio è generico di proposito. Il motivo è nel registro: docker compose logs app. Le cause tipiche sono un URI di reindirizzamento non identico ai due capi, un segreto client sbagliato, un emittente senza la barra finale, o un account del provider senza indirizzo email.

Nessuno viene aggiunto alla biblioteca. Controlla, in ordine: il gruppo è in Aggiungi per gruppo SSO di quella biblioteca e il nome coincide esattamente con quello del provider, maiuscole incluse; il provider invia i gruppi (l'ambito profile in Authentik, e OIDC_GROUPS_CLAIM se hai rinominato il campo); e la persona ha effettuato di nuovo l'accesso dopo la modifica.

L'accesso fallisce subito e il registro dice invalid_request. In Authentik, apri il provider e controlla che consenta il flusso Authorization Code. Un provider senza alcun tipo di concessione consentito rifiuta tutti gli accessi.

Voglio che le persone possano continuare a usare le password. Non serve fare nulla, restano disponibili entrambe. Per chiudere l'iscrizione con password mantenendo l'SSO, imposta REGISTRATION_ENABLED=false. Per chiudere del tutto le password, vedi la modalità solo SSO.