Guide
Guide
Keycloak, LemonLDAP::NG, Authentik, Okta, Google… : sus usuarios entran en SpotBooker con las credenciales de su organización.
¿Su organización tiene un proveedor de identidad que habla OpenID Connect (OIDC)? Es el caso de Keycloak, LemonLDAP::NG, Authentik, Okta o Google Workspace. Una vez conectado a SpotBooker, cada persona inicia sesión con sus credenciales habituales, sin una contraseña más. El inicio de sesión OpenID Connect está incluido en la suscripción; como el inicio de sesión SAML, requiere acceso completo (suscripción o prueba en curso). Solo los administradores de su espacio lo configuran, normalmente con el servicio informático.
Su dirección (el emisor) debe ser HTTPS y estar accesible desde Internet: SpotBooker rechaza las direcciones de red privada y las que contienen un ? o un #.
Hay que poder declarar allí una aplicación: un cliente confidencial (con secreto), con el flujo de código de autorización. SpotBooker envía siempre además PKCE (S256).
Por ejemplo instituto.es. A diferencia de SAML, el inicio de sesión OpenID Connect no se activa sin dominio: un mismo proveedor (Google, Okta…) puede servir a muchas organizaciones, y sin dominio todas sus cuentas podrían entrar.
Permite probar que el dominio es suyo (véase «Probar sus dominios» más abajo). Esta prueba es indispensable para que sus usuarios lleguen a la conexión desde la página de inicio de sesión: sin ella, el correo escrito no encuentra su organización, la admisión automática no actúa y una cuenta ya existente no puede vincularse por su correo.
Su proveedor solo conecta una aplicación que conoce. El recuadro «Para declarar en su proveedor» muestra dos direcciones, cada una con un botón Copiar: la URL de redirección, con la forma https://<su-espacio>/oidc/<clave>/callback, y la URL de redirección tras el cierre de sesión, https://<su-espacio>/oidc/<clave>/logged-out. La clave es estable: estas direcciones no cambian, aunque modifique la dirección pública de su espacio.
Cree una aplicación de tipo cliente confidencial, con el flujo de código de autorización (authorization code). Declare la URL de redirección del paso 1; declare la URL posterior al cierre de sesión solo si su proveedor ofrece cierre de sesión centralizado. Anote el identificador del cliente y su secreto. Las recetas de Keycloak y LemonLDAP::NG están más abajo.
En SpotBooker, elija el tipo de proveedor (solo rellena la ayuda), introduzca el emisor tal como lo publica el proveedor y pulse «Probar el proveedor». La prueba lee /.well-known/openid-configuration y las claves de firma, sin guardar nada. El secreto, en cambio, solo se comprueba en el primer inicio de sesión real.
Copie el identificador del cliente y su secreto (cifrado al guardar, nunca se vuelve a mostrar). La autenticación en el punto de token es client_secret_basic por defecto; elija client_secret_post solo si su proveedor lo exige. Los scopes por defecto son openid email profile; openid se añade siempre.
Los claims son los datos que el proveedor coloca en el token de la persona. Por defecto: sub (identificador único), email, given_name (nombre), family_name (apellidos) y groups. Un claim puede ser una ruta anidada, por ejemplo realm_access.roles. Si faltan el correo o los nombres en el token, SpotBooker lee el punto userinfo del proveedor, tras comprobar que se trata del mismo sub.
La activación exige: un descubrimiento correcto del proveedor, el identificador del cliente, el secreto y al menos un dominio aceptado. Si falta alguno, SpotBooker lo indica y no activa nada. Cada modificación del inicio de sesión queda registrada en el registro de actividad.
En su realm, abra Clients y luego Create client. Tipo de cliente: OpenID Connect. En el paso siguiente, active Client authentication (acceso confidencial) y mantenga marcado Standard flow (código de autorización). El secreto está después en la pestaña Credentials.
En «Valid redirect URIs», pegue la URL de redirección copiada en el paso 1. Si quiere el cierre de sesión centralizado, pegue la URL posterior al cierre en «Valid post logout redirect URIs». El emisor tiene la forma https://servidor/realms/nombre, sin / final.
Para recibir los grupos, abra el cliente, pestaña Client scopes, luego el scope dedicado del cliente (…-dedicated) y Add mapper > By configuration > Group Membership. Llámelo groups, ponga groups en «Token Claim Name» y desactive «Full group path» si quiere nombres simples (labo y no /labo). Para los roles del realm, use mejor el claim realm_access.roles.
Un correo enviado con email_verified: false no se considera fiable para vincular una cuenta de SpotBooker ya existente. En Keycloak, marque los correos como verificados (usuario: «Email verified»); si no, quienes ya tengan cuenta deberán iniciar sesión con su contraseña.
En el Manager, añada un «OpenID Connect Relying Party» (RP) para SpotBooker, con un identificador de cliente y un secreto. El emisor que debe introducir en SpotBooker es la dirección del portal de LemonLDAP::NG, por ejemplo https://auth.example.fr. Para esta relación, el identificador y el secreto están en Options → Basic (Client ID, Client secret).
Añada la URL de redirección del paso 1 a las direcciones de redirección permitidas de la relación (y la URL posterior al cierre de sesión para el cierre centralizado). Para la autenticación en el punto de token, mantenga client_secret_basic, que es también el valor por defecto de SpotBooker.
En los atributos exportados de la relación, asocie los claims email, given_name y family_name a los atributos de su directorio (por ejemplo mail, givenName, sn), y groups si quiere gestionar los grupos. Añada el scope correspondiente en SpotBooker si LemonLDAP::NG lo exige.
Introduzca el emisor exactamente como lo publica su proveedor: SpotBooker no corrige nada en silencio. Si el emisor publicado difiere del que escribió, aunque sea por una / final, la prueba lo indica y muestra ambos valores: copie el del proveedor. Ejemplo: Keycloak publica https://<servidor>/realms/<realm>, sin / final.
La dirección que se introduce es la del emisor, no la del documento de descubrimiento: sin /.well-known/openid-configuration.
HTTPS obligatorio, accesible desde Internet, sin ? ni #. Se rechaza una dirección de red privada: un proveedor detrás del cortafuegos de la organización debe hacerse accesible desde Internet.
Un dominio que declara filtra las direcciones en cuanto se guarda. Para que además encuentre su organización desde la página de inicio de sesión, certifique las direcciones y admita automáticamente, debe probar que le pertenece. Sin esa prueba, cualquier espacio podría reclamar su dominio. La prueba vale para el dominio exacto: institut.fr no cubre labo.institut.fr, que se declara y se prueba por separado.
Bajo el campo de dominios, cada dominio guardado muestra su registro: tipo TXT, valor spotbooker-verification=….
Su servicio informático lo añade en el propio dominio (por ejemplo institut.fr) o, si lo prefiere, en _spotbooker.institut.fr. Puede quedarse: SpotBooker lo vuelve a comprobar cada día.
Haga clic en «Verificar ahora». Si no, SpotBooker lo busca solo cada 15 minutos durante 14 días. Un dominio lo verifica un solo espacio: si ya lo está en otro, contacte con el soporte. Si el registro desaparece 7 días seguidos, se retira la verificación y sus administradores reciben un aviso por correo.
En «Correspondencia de grupos», asocie un valor de grupo del proveedor a un grupo de SpotBooker creado antes. En cada inicio de sesión, la persona se añade a los grupos que corresponden a los suyos en el proveedor y se retira de los que ha dejado. Un grupo creado a mano en SpotBooker nunca lo modifica el inicio de sesión.
El proveedor debe enviar el claim groups (o el que haya indicado). Con Keycloak, es el mapper «Group Membership» de arriba; para los roles, indique realm_access.roles. Google no envía grupos: limite entonces el acceso por dominio.
Cuando la persona cierra sesión en SpotBooker, también se cierra en el proveedor (RP-Initiated Logout) y vuelve a la página de inicio de sesión con este mensaje de confirmación: «Ha cerrado sesión, también en su organización.». Recuerde declarar la URL posterior al cierre de sesión en el proveedor.
Si el proveedor no publica un punto de cierre de sesión, solo se cierra la sesión de SpotBooker: la persona sigue conectada en el proveedor. El recuadro de estado del inicio de sesión indica si el cierre centralizado está disponible.
El token de identidad se verifica siempre con las claves que publica el proveedor (RS256, RS384, RS512, PS256, ES256, ES384). Se rechazan los tokens sin firma (none) y las firmas HMAC (HS256 y otras).
Un correo enviado con email_verified: false no se considera fiable para vincular una cuenta existente: se invita a la persona a iniciar sesión con su contraseña.
| Lo que ve | Qué hacer |
|---|---|
| « El inicio de sesión a través de su organización no está disponible. Póngase en contacto con su administrador. » | El inicio de sesión no está activado, está incompleto o no se pudo leer el proveedor. En Ajustes, compruebe que está activado y que el estado del proveedor indica «Detectado el» seguido de una fecha (y no «Aún no detectado»), y lance la prueba. |
| « El inicio de sesión a través de su organización ha fallado. Inténtelo de nuevo. » | Causa más frecuente: la URL de redirección no está declarada de forma idéntica en el proveedor, o el secreto es erróneo. Compruebe también el método de autenticación (client_secret_basic o client_secret_post) y el emisor. El «Último error» del recuadro de estado da el motivo; una página de inicio de sesión abierta demasiado tiempo también falla: empiece de nuevo. Puede que el proveedor no haya enviado ni el correo ni el identificador (sub) en los claims que configuró, ni siquiera tras la lectura del punto userinfo: compruebe los nombres en «Lectura de los claims». |
| « Su cuenta no está autorizada a acceder a este espacio. Póngase en contacto con el administrador de su organización. » | El correo de la persona está fuera de los dominios aceptados, ya lo usa una cuenta de otro espacio SpotBooker, o un administrador rechazó la solicitud de acceso de esta persona. En el primer caso, añada el dominio; en los demás, una persona rechazada no entra volviendo a iniciar sesión. |
| « Ya existe una cuenta con esta dirección. Por motivos de seguridad, la vinculación automática no es posible: inicie sesión con su contraseña. » | Ya existe una cuenta de SpotBooker con este correo y el proveedor no lo declara verificado (email_verified). Marque el correo como verificado en el proveedor, o la persona inicia sesión con su contraseña. |
| « Su solicitud de acceso se ha enviado al administrador de su organización. Recibirá un correo cuando se haya tramitado. » | Es normal cuando la admisión automática está desactivada o el dominio no está probado por DNS: un administrador debe aceptar la solicitud en la gestión de usuarios. |
| « Su solicitud de acceso está pendiente de validación por un administrador. » | La persona ya solicitó el acceso: un administrador aún no ha decidido. Acepte o rechace la solicitud. |
| « Su cuenta ha sido desactivada por su organización. Póngase en contacto con su administrador. » | La cuenta se desactivó porque la persona salió del directorio. Se reabre sola cuando el directorio la marca de nuevo como activa; no se reactiva a mano en SpotBooker. Consulte Sincronizar usuarios con SCIM. |
| « Obligatorio para activar el inicio de sesión OpenID Connect (proveedor detectado, identificador, secreto y al menos un dominio). » | Falta una condición: proveedor descubierto, identificador del cliente, secreto o al menos un dominio aceptado. Lance la prueba, complete los campos y vuelva a activar. |
| « Se rechaza la dirección del proveedor: no usa HTTPS, o contiene una consulta (?), un fragmento (#) o caracteres no permitidos. » | El emisor no está en HTTPS, o contiene un ? o un #. Introduzca solo la dirección del emisor, en HTTPS. |
| « Esta dirección apunta a una red privada: SpotBooker no se conecta a ella. » | La dirección apunta a una máquina de una red privada. Haga el proveedor accesible desde Internet y use su dirección pública. |
| « No se puede contactar con el proveedor. Compruebe la dirección y que el servidor sea accesible desde Internet. » | Dirección mal escrita, o servidor inaccesible desde Internet (cortafuegos, certificado HTTPS no válido). Compruebe la dirección y ábrala en un navegador fuera de la organización. |
| « El proveedor respondió con un error. Compruebe el emisor: la dirección no debe incluir /.well-known/openid-configuration. » | La dirección introducida no es la de un proveedor OpenID Connect. Quite /.well-known/openid-configuration y compruebe la ruta (con Keycloak: /realms/<realm>). |
| « El emisor introducido (https://sso.example.fr/) no coincide con el que publica el proveedor (https://sso.example.fr). Cópielo idéntico, carácter por carácter (incluida una « / » final). » | El emisor introducido difiere del que publica el proveedor. Copie el valor encontrado, carácter por carácter, incluida una / final. SpotBooker no lo corrige por usted. |
| « El documento del proveedor está incompleto: falta una dirección indispensable (autorización, token o claves). » | El documento del proveedor no contiene todas las direcciones necesarias. Compruebe la configuración del proveedor o del realm. |
| « Se guardó el inicio de sesión, pero falló la detección del proveedor: … » | Los ajustes están guardados, pero el inicio de sesión no puede usarse hasta que el descubrimiento tenga éxito. Corrija la causa indicada y lance la prueba. |
| « La respuesta del proveedor no es un documento OpenID Connect legible. » | La dirección no lleva a un proveedor OpenID Connect (página web, portal, redirección). Compruebe el emisor. |
| « La respuesta del proveedor es anormalmente grande y se ha rechazado. » | Una respuesta anormalmente voluminosa no se lee. Compruebe que la dirección es realmente la de un proveedor OpenID Connect. |
| « La prueba ha fallado. Compruebe el emisor introducido. » | El mensaje no da detalles: compruebe el emisor introducido y vuelva a lanzar la prueba. |