Skip to content

Configurar el inicio de sesión con Keycloak (SSO) ​

Acceso

Ruta: ¡Hola! Store → Keycloak → Instalar

Visión general ​

La app Keycloak permite que los usuarios inicien sesión en ¡Hola! Suite con las credenciales de Keycloak de la empresa, sin escribir la contraseña de ¡Hola! Suite. Este tipo de acceso se llama inicio de sesión único, o SSO (Single Sign-On).

Además del inicio de sesión, Keycloak puede definir el grupo de permisos de cada usuario en ¡Hola! Suite, a partir de los grupos o funciones que el usuario tiene en Keycloak. Si quieres, ¡Hola! Suite también crea automáticamente el usuario en el primer inicio de sesión.

Requisitos previos ​

  • Permiso para visualizar ¡Hola! Store en tu grupo de permisos.
  • Acceso de administrador al Keycloak de la empresa.
  • Grupos de permisos del tipo sistema ya creados en ¡Hola! Suite, para el mapeo. Consulta Grupo de permisos.
  • Ninguna otra app de SSO instalada. ¡Hola! Suite acepta una app de SSO a la vez.

Paso a paso ​

1. Crear el cliente en Keycloak ​

  1. En la consola de administración de Keycloak, en el realm de la empresa, accede a Clients y haz clic en Create client.
  2. Elige el tipo OpenID Connect e informa un Client ID (ej.: "opa-suite").
  3. Activa Client authentication y deja marcado el Standard flow.
  4. En Valid redirect URIs, informa la dirección de abajo, reemplazando por la dirección de tu ¡Hola! Suite: https://endereco-do-seu-opa-suite/auth/login/sso/callback/keycloak
  5. Guarda y copia el secreto del cliente en la pestaña Credentials.
  6. Si vas a mapear permisos, configura en el cliente un mapeador que envíe los grupos o funciones del usuario en la información del usuario (userinfo). El nombre de ese dato es lo que va en el campo Claim name.

Las URLs del realm siguen este patrón (documentación de Keycloak):

URLDirección
Autenticaciónhttps://seu-keycloak/realms/seu-realm/protocol/openid-connect/auth
Tokenhttps://seu-keycloak/realms/seu-realm/protocol/openid-connect/token
Recursos (datos del usuario)https://seu-keycloak/realms/seu-realm/protocol/openid-connect/userinfo
Versiones antiguas de Keycloak

En versiones antiguas, las direcciones pueden tener /auth antes de /realms. Verifica la dirección de tu servidor.

2. Instalar la app en ¡Hola! Suite ​

  1. Accede a ¡Hola! Store y abre la app Keycloak, en la categoría SSO.
  2. Haz clic en Instalar. Se abre la ventana Instalar Keycloak con cuatro etapas.
  3. En la etapa Credenciales del cliente OAuth, completa ID del cliente y Clave privada del cliente. Haz clic en Continuar.
  4. En la etapa Configure las URLs de su servidor, completa URL de autenticación, URL del token y URL de recursos. Haz clic en Continuar.
  5. En la etapa Campos de identificación, completa:
    • Campo de identificación del usuario: el dato que identifica al usuario en la respuesta de Keycloak. Usa email, porque ¡Hola! Suite busca al usuario por el correo electrónico.
    • Scopes: los permisos solicitados a Keycloak en el inicio de sesión (ej.: openid profile email).
    • Claim name (opcional): la ruta de los grupos o funciones en la respuesta de Keycloak. Usa puntos para niveles anidados (ej.: roles.domain.teams).
  6. Haz clic en Continuar.
  7. En la etapa Mapeo de permisos, configura:
    • Crear usuario automáticamente si no existe: actívalo para que ¡Hola! Suite cree el usuario en el primer inicio de sesión.
    • Grupo de permisos predeterminado: el grupo usado cuando el usuario no tiene ningún permiso mapeado. Obligatorio cuando la creación automática está activa.
    • Pares de Permiso de Keycloak y Grupo de permisos: escribe el nombre del grupo o función tal como viene de Keycloak y elige el grupo de permisos correspondiente en ¡Hola! Suite. Agrega cuantos pares necesites.
  8. Haz clic en Instalar SSO de Keycloak.

Resultado esperado ​

La app aparece como instalada y ¡Hola! Suite abre la pantalla de configuraciones, con las secciones Datos de integración y Mapeo de permisos.

En la pantalla de inicio de sesión de ¡Hola! Suite pasa a aparecer, debajo de Iniciar sesión, el texto o inicie sesión con y el botón SSO. Al hacer clic, el usuario es llevado al inicio de sesión de Keycloak y, después de autenticado, vuelve a ¡Hola! Suite ya conectado.

En cada inicio de sesión por Keycloak, ¡Hola! Suite:

  1. Busca al usuario por el correo electrónico.
  2. Define el grupo de permisos por el primer grupo del usuario en Keycloak que tenga correspondencia en el mapeo. Sin correspondencia, usa el Grupo de permisos predeterminado.
  3. Actualiza el nombre del usuario con el nombre que viene de Keycloak y deja al usuario activo.
  4. Si el usuario no existe y la creación automática está activa, crea el usuario, siempre que haya una licencia de usuario libre.

El inicio de sesión con Keycloak también sigue las reglas de seguridad del inicio de sesión común: autenticación de dos factores, límite de usuarios conectados y restricción de acceso por IP.

El grupo de permisos se sobrescribe en cada inicio de sesión

El grupo de permisos definido por el mapeo reemplaza el que esté en el registro del usuario en ¡Hola! Suite. Para cambiar el permiso de alguien, modifica el grupo en Keycloak o el mapeo.

Configuraciones disponibles ​

Para modificar, accede a ¡Hola! Store → Keycloak → Acceder.

SecciónCampos
Datos de integraciónClient ID, Client Secret, URL de autenticación, URL del token, URL de recursos, Campo de identificación del usuario, Scopes y Claim name.
Mapeo de permisosCrear usuario automáticamente si no existe, Grupo de permisos predeterminado y los pares Permiso de Keycloak y Grupo de permisos.

Para eliminar el inicio de sesión con Keycloak, haz clic en Desinstalar App y confirma en Desinstalar.

Problemas comunes ​

Síntoma o mensajeQué verificar
"No fue posible crear tu usuario. Ponte en contacto con un administrador del sistema."¡Hola! Suite no encontró un grupo de permisos para el usuario. Verifica el Claim name, los pares del mapeo y el Grupo de permisos predeterminado.
"Tu usuario no fue encontrado. Ponte en contacto con un administrador del sistema."El usuario no existe en ¡Hola! Suite y la creación automática está desactivada.
"¡La cantidad de usuarios superó el límite contratado!"No hay licencia libre para crear el usuario, o se alcanzó el límite de usuarios conectados.
"No fue posible iniciar sesión con este proveedor. Ponte en contacto con el administrador del sistema."La respuesta de Keycloak no trajo el Campo de identificación del usuario configurado. Verifica el campo y los Scopes.
"Hubo un error al recopilar los datos de tu usuario. Inténtalo de nuevo más tarde."Keycloak rechazó el intercambio de datos. Verifica el ID del cliente, la Clave privada del cliente y las URLs.
La página de la app muestra "Ya hay una app de esta categoría instalada"Ya hay otra app de SSO instalada. Desinstálala antes de instalar Keycloak.

Buenas prácticas ​

  • Usa un Grupo de permisos predeterminado con el mínimo de acceso, para quien aún no tiene un grupo mapeado.
  • Mapea todos los grupos de Keycloak que necesitan un acceso diferente, para que nadie caiga en el grupo predeterminado por error.
  • Prueba el inicio de sesión con un usuario de cada grupo antes de habilitarlo para el equipo.

Contenidos relacionados ​