Inici de sessió únic

Vaultisse permet que la gent iniciï sessió amb un compte que ja té a la vostra organització, mitjançant OpenID Connect (OIDC). Funciona amb Authentik, Keycloak, Authelia i qualsevol altre proveïdor que parli OIDC. Els exemples de sota fan servir Authentik.

La contrasenya continua funcionant al costat de l'SSO, tret que activeu el mode només SSO. Quan l'SSO està activat, la pàgina d'inici de sessió mostra un botó més:

Com es comporta

• La primera vegada que algú inicia sessió amb SSO, Vaultisse li crea un compte, amb la seva pròpia biblioteca i sense pas d'aprovació. Entra qui el proveïdor d'identitat deixi entrar, així que controleu l'accés allà. REGISTRATION_REQUIRES_APPROVAL i REGISTRATION_ENABLED no s'apliquen a l'SSO.
• Si una persona ja té un compte amb contrasenya amb el mateix correu, i el proveïdor diu que aquest correu està verificat, l'SSO es vincula a aquest compte i conserva una sola biblioteca. Un correu que el proveïdor no ha verificat no s'utilitza mai per vincular comptes.
• Els inicis de sessió SSO se salten la verificació en dos passos pròpia de Vaultisse, perquè el proveïdor ja ha fet aquest pas si l'exigiu.
• Tancar la sessió acaba només la sessió de Vaultisse. No tanca la sessió de la persona al proveïdor.
• Cada inici d'SSO demana al proveïdor que autentiqui de nou (prompt=login), així que un ordinador compartit mai no reutilitza en silenci la sessió de la persona anterior.

1. Creeu l'aplicació al proveïdor

A Authentik, creeu una aplicació amb un proveïdor OAuth2/OpenID. Els noms dels menús canvien entre versions; els valors que necessiteu són:

Paràmetre	Valor
Tipus de client	Confidential
URI de redirecció / callback	https://books.example.com/auth/oidc/callback, coincidint exactament
Àmbits (scopes)	openid, profile, email

Després anoteu tres coses del proveïdor: el Client ID, el Client secret i l'adreça de l'emissor (issuer). A Authentik l'emissor té aquest aspecte: https://auth.example.com/application/o/vaultisse/, amb la barra final.

A Authentik, qui pot obrir l'aplicació és qui pot iniciar sessió a Vaultisse, així que vinculeu-la als grups o usuaris que vulgueu.

2. Configureu Vaultisse

Afegiu això 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 ha de ser idèntica a la registrada al proveïdor, caràcter per caràcter. A propòsit no es dedueix de la barra d'adreces. Apliqueu-ho:

docker compose up -d

Torneu a carregar la pàgina d'inici de sessió: el botó hi hauria de ser. Per canviar-ne el text, definiu OIDC_BUTTON_LABEL. Si treballeu darrere d'un intermediari, cal TRUST_PROXY=true com sempre, consulteu Servidor intermediari invers i HTTPS.

3. Accés a la biblioteca segons grups (opcional)

Beta: aquesta part és nova a 1.3.7-beta.1. Consulteu Provar una beta.

D'entrada, l'SSO només decideix qui pot iniciar sessió. Després, cada persona és convidada a mà a les biblioteques compartides, consulteu Compartir una biblioteca i rols.

Si la vostra gent ja pertany a grups al proveïdor, podeu deixar que aquests grups decideixin qui és a quina biblioteca, i amb quin rol. No cal convidar ningú una per una: si sou al grup, sou a la biblioteca, i si deixeu el grup, perdeu l'accés.

Al servidor, només cal definir una cosa, i potser ni això: el nom del camp que porta els grups. Per defecte és groups, i Authentik l'inclou amb l'àmbit profile. Si el vostre proveïdor fa servir un altre nom, definiu OIDC_GROUPS_CLAIM.

A cada biblioteca, un administrador llista els grups que hi tenen accés. Obriu el diàleg Gestiona de la biblioteca, cerqueu Afegeix per grup SSO, afegiu una línia per grup amb el nom del grup tal com l'escriu el proveïdor, trieu el rol i feu clic a Desa:

Grup SSO	Rol
family-users	Normal
library-admins	Admin

Com funciona, a cada inici de sessió amb SSO:

• La persona s'afegeix a totes les biblioteques on aparegui un dels seus grups, acceptada a l'instant, amb el rol més alt entre els grups que coincideixen. Qui és a family-users i a library-admins esdevé administrador.
• Cada biblioteca decideix per ella mateixa. Cadascuna llista els seus propis grups, de manera que una persona només entra a les biblioteques a les quals associeu els seus grups, i el mateix grup pot tenir rols diferents a biblioteques diferents.
• Quan una persona ja no té cap grup de la llista, és eliminada d'aquesta biblioteca en el seu proper inici de sessió. Fins que no torni a iniciar sessió no canvia res, perquè els grups es llegeixen en iniciar sessió.
• Si encara té llibres en préstec d'aquesta biblioteca, no és eliminada. Passa a ser Restricted: no pot agafar res de nou en préstec, però els seus préstecs continuen registrats i es poden retornar. Quan ho retorni tot i torni a iniciar sessió sense grup, és eliminada. Si recupera un grup, recupera el seu rol.
• Les persones afegides a mà mai no les elimina l'SSO, ni tampoc la biblioteca personal de ningú. Si un administrador tria un rol a mà per a algú que ha afegit l'SSO, aquesta persona passa a ser també un membre manual.
• Una biblioteca sense grups a la llista continua sent totalment manual.
• Si el proveïdor no envia cap grup en un inici de sessió (per exemple, falta l'àmbit profile), Vaultisse deixa intacte l'accés de tothom en aquell inici de sessió, perquè un proveïdor mal configurat no pugui buidar les vostres biblioteques.
• Una biblioteca sempre conserva un administrador, i un grup no pot donar el rol Borrower en una biblioteca amb els préstecs desactivats. Quan un canvi trencaria una regla, s'omet i s'escriu al registre del servidor. L'inici de sessió funciona igualment.

Si actualitzeu des de la 1.3.6: OIDC_GROUP_ROLES i l'opció Segons els grups SSO ja no existeixen. Esborreu OIDC_GROUP_ROLES del vostre .env (s'ignora) i llisteu els vostres grups a cada biblioteca. Els membres que seguien els grups SSO passen a ser membres manuals normals.

4. Biblioteques personals (opcional)

Per defecte, una persona nova que entra amb SSO rep una biblioteca pròpia en el primer inici de sessió, com qualsevol compte nou. Si voleu que vegi només les biblioteques que li donen els seus grups, desactiveu-ho:

OIDC_PERSONAL_VAULT=false

Això només afecta qui inicia sessió amb SSO per primera vegada després del canvi. Els comptes existents conserven la seva biblioteca.

5. Mode només SSO (opcional)

Perquè el proveïdor sigui l'única font de veritat sobre qui entra, tanqueu del tot la porta de la contrasenya:

SSO_ONLY=true

Amb això activat, l'inici de sessió amb contrasenya i el registre queden desactivats, i la pàgina d'accés mostra només el botó d'SSO. S'ignora si l'SSO no està completament configurat, de manera que un error als valors OIDC_ no pot deixar tothom fora. Recordeu de conservar una manera d'arribar vosaltres mateixos al proveïdor abans d'activar-lo.

Resolució de problemes

No apareix "Sign in with SSO". Un dels quatre valors OIDC_ obligatoris és buit, o DEMO_MODE està activat. Comproveu-ho amb docker compose exec app env | grep OIDC_.

L'inici de sessió torna a la pàgina d'accés amb un error. El missatge és genèric a propòsit. El motiu és al registre: docker compose logs app. Les causes habituals són una URI de redirecció que no és idèntica en tots dos extrems, un secret de client erroni, un emissor sense la barra final, o un compte del proveïdor sense adreça de correu.

No s'afegeix ningú a la biblioteca. Comproveu, per ordre: el grup és a Afegeix per grup SSO d'aquella biblioteca i el nom coincideix exactament amb el del proveïdor, majúscules incloses; el proveïdor envia els grups (l'àmbit profile a Authentik, i OIDC_GROUPS_CLAIM si heu canviat el nom del camp); i la persona va tornar a iniciar sessió després del canvi.

L'inici de sessió falla a l'instant i el registre diu invalid_request. A Authentik, obriu el proveïdor i comproveu que permet el flux Authorization Code. Un proveïdor sense cap tipus de concessió permès rebutja tots els inicis de sessió.

Vull que la gent pugui continuar fent servir contrasenyes. No cal fer res, totes dues continuen disponibles. Per tancar l'alta amb contrasenya mantenint l'SSO, definiu REGISTRATION_ENABLED=false. Per tancar les contrasenyes del tot, consulteu el mode només SSO.