Inicio de sesión único

Vaultisse permite que la gente inicie sesión con una cuenta que ya tiene en tu organización, mediante OpenID Connect (OIDC). Funciona con Authentik, Keycloak, Authelia y cualquier otro proveedor que hable OIDC. Los ejemplos de abajo usan Authentik.

La contraseña sigue funcionando junto al SSO, salvo que actives el modo solo SSO. Cuando el SSO está activado, la página de inicio de sesión muestra un botón más:

Cómo se comporta

• La primera vez que alguien inicia sesión con SSO, Vaultisse le crea una cuenta, con su propia biblioteca y sin paso de aprobación. Entra quien el proveedor de identidad deje entrar, así que controla el acceso allí. REGISTRATION_REQUIRES_APPROVAL y REGISTRATION_ENABLED no se aplican al SSO.
• Si una persona ya tiene una cuenta con contraseña con el mismo correo, y el proveedor dice que ese correo está verificado, el SSO se vincula a esa cuenta y conserva una sola biblioteca. Un correo que el proveedor no ha verificado nunca se usa para vincular cuentas.
• Los inicios de sesión SSO se saltan la verificación en dos pasos propia de Vaultisse, porque el proveedor ya hizo ese paso si lo exiges.
• Cerrar sesión termina solo la sesión de Vaultisse. No cierra la sesión de la persona en el proveedor.
• Cada inicio de SSO pide al proveedor que autentique de nuevo (prompt=login), así que un ordenador compartido nunca reutiliza en silencio la sesión de la persona anterior.

1. Crea la aplicación en el proveedor

En Authentik, crea una aplicación con un proveedor OAuth2/OpenID. Los nombres de los menús cambian entre versiones; los valores que necesitas son:

Ajuste	Valor
Tipo de cliente	Confidential
URI de redirección / callback	https://books.example.com/auth/oidc/callback, coincidiendo exactamente
Ámbitos (scopes)	openid, profile, email

Después anota tres cosas del proveedor: el Client ID, el Client secret y la dirección del emisor (issuer). En Authentik el emisor tiene este aspecto: https://auth.example.com/application/o/vaultisse/, con la barra final.

En Authentik, quien puede abrir la aplicación es quien puede iniciar sesión en Vaultisse, así que vincúlala a los grupos o usuarios que quieras.

2. Configura Vaultisse

Añade esto 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 debe ser idéntica a la registrada en el proveedor, carácter por carácter. A propósito no se deduce de la barra de direcciones. Aplícalo:

docker compose up -d

Recarga la página de inicio de sesión: el botón debería estar ahí. Para cambiar su texto, define OIDC_BUTTON_LABEL. Si trabajas detrás de un proxy, hace falta TRUST_PROXY=true como siempre, consulta Proxy inverso y HTTPS.

3. Acceso a la biblioteca según grupos (opcional)

Beta: esta parte es nueva en 1.3.7-beta.1. Consulta Probar una beta.

De entrada, el SSO solo decide quién puede iniciar sesión. Después, a cada persona se la invita a mano a las bibliotecas compartidas, consulta Compartir una biblioteca y roles.

Si tu gente ya pertenece a grupos en el proveedor, puedes dejar que esos grupos decidan quién está en qué biblioteca, y con qué rol. No hace falta invitar a nadie una a una: si estás en el grupo, estás en la biblioteca, y si sales del grupo, pierdes el acceso.

En el servidor, solo puede hacer falta definir una cosa: el nombre del campo que lleva los grupos. Por defecto es groups, y Authentik lo incluye con el ámbito profile. Si tu proveedor usa otro nombre, define OIDC_GROUPS_CLAIM.

En cada biblioteca, un administrador enumera los grupos que tienen acceso. Abre el diálogo Gestionar de la biblioteca, busca Añadir por grupo SSO, añade una línea por grupo con el nombre del grupo tal como lo escribe el proveedor, elige el rol y pulsa Guardar:

Grupo SSO	Rol
family-users	Normal
library-admins	Admin

Cómo funciona, en cada inicio de sesión con SSO:

• La persona se añade a todas las bibliotecas donde aparezca uno de sus grupos, aceptada al momento, con el rol más alto entre los grupos que coinciden. Quien está en family-users y en library-admins pasa a ser administrador.
• Cada biblioteca decide por sí misma. Cada una enumera sus propios grupos, así que una persona solo entra en las bibliotecas a las que asocies sus grupos, y el mismo grupo puede tener roles distintos en bibliotecas distintas.
• Cuando una persona ya no tiene ningún grupo de la lista, se la quita de esa biblioteca en su siguiente inicio de sesión. Hasta que vuelva a iniciar sesión no cambia nada, porque los grupos se leen al iniciar sesión.
• Si aún tiene libros prestados de esa biblioteca, no se la quita. Pasa a ser Restricted: no puede pedir nada nuevo prestado, pero sus préstamos siguen registrados y se pueden devolver. Cuando devuelva todo y vuelva a iniciar sesión sin grupo, se la quita. Si recupera un grupo, recupera su rol.
• Las personas añadidas a mano nunca las quita el SSO, ni tampoco la biblioteca personal de nadie. Si un administrador elige un rol a mano para alguien que añadió el SSO, esa persona pasa a ser también un miembro manual.
• Una biblioteca sin grupos en la lista sigue siendo totalmente manual.
• Si el proveedor no envía ningún grupo en un inicio de sesión (por ejemplo, falta el ámbito profile), Vaultisse deja intacto el acceso de todo el mundo en ese inicio de sesión, para que un proveedor mal configurado no pueda vaciar tus bibliotecas.
• Una biblioteca siempre conserva un administrador, y un grupo no puede dar el rol Borrower en una biblioteca con los préstamos desactivados. Cuando un cambio rompería una regla, se omite y se escribe en el registro del servidor. El inicio de sesión funciona igualmente.

Si actualizas desde la 1.3.6: OIDC_GROUP_ROLES y la opción Según los grupos SSO ya no existen. Borra OIDC_GROUP_ROLES de tu .env (se ignora) y enumera tus grupos en cada biblioteca. Los miembros que seguían los grupos SSO pasan a ser miembros manuales normales.

4. Bibliotecas personales (opcional)

Por defecto, una persona nueva que entra con SSO recibe una biblioteca propia en su primer inicio de sesión, como cualquier cuenta nueva. Si quieres que vea solo las bibliotecas que le dan sus grupos, desactívalo:

OIDC_PERSONAL_VAULT=false

Esto solo afecta a quien inicie sesión con SSO por primera vez después del cambio. Las cuentas existentes conservan su biblioteca.

5. Modo solo SSO (opcional)

Para que el proveedor sea la única fuente de verdad sobre quién entra, cierra del todo la puerta de la contraseña:

SSO_ONLY=true

Con esto activado, el inicio de sesión con contraseña y el registro quedan desactivados, y la página de acceso muestra solo el botón de SSO. Se ignora si el SSO no está completamente configurado, así que un error en los valores OIDC_ no puede dejar fuera a todo el mundo. Acuérdate de conservar una forma de llegar tú mismo al proveedor antes de activarlo.

Solución de problemas

No aparece "Sign in with SSO". Uno de los cuatro valores OIDC_ obligatorios está vacío, o DEMO_MODE está activado. Compruébalo con docker compose exec app env | grep OIDC_.

El inicio de sesión vuelve a la página de acceso con un error. El mensaje es genérico a propósito. El motivo está en el registro: docker compose logs app. Las causas habituales son una URI de redirección que no es idéntica en ambos extremos, un secreto de cliente erróneo, un emisor sin su barra final, o una cuenta del proveedor sin dirección de correo.

No se añade a nadie a la biblioteca. Comprueba, por orden: el grupo está en Añadir por grupo SSO de esa biblioteca y el nombre coincide exactamente con el del proveedor, mayúsculas incluidas; el proveedor envía los grupos (el ámbito profile en Authentik, y OIDC_GROUPS_CLAIM si cambiaste el nombre del campo); y la persona volvió a iniciar sesión después del cambio.

El inicio de sesión falla al instante y el registro dice invalid_request. En Authentik, abre el proveedor y comprueba que permite el flujo Authorization Code. Un proveedor sin ningún tipo de concesión permitido rechaza todos los inicios de sesión.

Quiero que la gente siga pudiendo usar contraseñas. No hay nada que hacer, ambas siguen disponibles. Para cerrar el alta con contraseña manteniendo el SSO, define REGISTRATION_ENABLED=false. Para cerrar las contraseñas del todo, consulta el modo solo SSO.