Usar SSO (inicio de sesión único) con Keycloak

Este artículo te guiará sobre cómo conectar a tus usuarios en Keycloak mediante el inicio de sesión único (SSO) a nuestra plataforma. Esta función sólo está disponible para clientes empresariales.

Este artículo cubre la integración SSO con nuestra plataforma basándose en un ejemplo con Keycloak.

• Si utilizas MS Azure Entra ID lee nuestro post sobre SSO para Microsoft Azure Active Directory.
• Si utilizas Okta, lee nuestro publicación sobre el SSO para Okta

Este post contiene detalles técnicos para administradores IAM o para tu departamento de
informática que gestione Keycloak. Por favor, ponte en contacto con un experto para que te ayude a configurar la conexión SSO.

SSO significa Inicio de sesión único. Es un proceso de autenticación que permite a un usuario acceder a varios servicios, como nuestra plataforma de Código QR, con un solo conjunto de credenciales de inicio de sesión (como nombre de usuario y contraseña). Con el SSO, los usuarios no necesitan recordar contraseñas diferentes para cada aplicación que utilicen, lo que agiliza el proceso de inicio de sesión y mejora la seguridad al reducir la necesidad de múltiples credenciales. Una vez autenticado, el usuario puede navegar entre varias aplicaciones o servicios sin necesidad de volver a iniciar sesión.

Tu empresa actúa como Proveedor de Identidad (IDP) que nos proporciona datos de usuario. Nuestra Plataforma de Marca Blanca actúa como un Proveedor de Servicios (PS) que recibe los datos de los usuarios y les da acceso a nuestro sistema.

La información básica sobre tu IDP y nuestro SP se intercambiará a través de las llamadas URL descriptoras.

Detrás de estas URLs hay archivos que describen el IDP (tu Keycloak) o SP con detalles para que el otro lado los procese automáticamente y ayude con la configuración.

Disfruta de las ventajas del IDP

La información del usuario se va a enviar a través de un mensaje SAML 2.0. En este mensaje los datos se codifican en Atributos. Al enviar la información desde tu Keycloak, un Mapeador de Salida está mapeando tus campos IDP internos, como nombre, apellidos, correo electrónico, etc. a Atributos SAML 2.0.

Cuando recibimos tu mensaje SAML 2.0 nuestro Mapeador de entrada transforma el Atributo SAML 2.0 de nuevo a nuestro formato interno e iniciaremos la sesión del usuario en nuestra plataforma.

Como primer paso tenemos que asegurarnos de que tu sistema Keycloak está preparado para ser un IDP (Proveedor de Identidad).

Siempre necesitas un reino sobre el que operar. El reino tiene usuarios almacenados en su interior. Estos usuarios tienen cierta información almacenada como nombre, apellidos y correo electrónico. También tienen determinados roles. El reino también estará conectado a nuestra Plataforma de Marca Blanca a través de un Cliente

Para la conexión SSO desde tu sistema Keycloak a nuestra Plataforma de Marca Blanca puedes utilizar un dominio ya existente (con usuarios ya dentro de él) o crear uno completamente nuevo.

Si quieres utilizar un nuevo reino sólo tienes que seguir los siguientes pasos.

Primero, asegúrate de que has iniciado sesión en tu sistema Keycloak como Administrador.

A continuación, haz clic en el menú desplegable situado justo debajo del logotipo de Keycloak, en la parte superior izquierda de la pantalla.

En la siguiente pantalla introduce un nombre de reino y pulsa sobre Crear. En nuestro ejemplo utilizamos TuReinoEmpresa.

Atención: Por favor, asegúrate de que no utilizas espacios ni caracteres especiales para el nombre del dominio, ya que se trata de un nombre de campo técnico y puede dar lugar a problemas. Después de crear un dominio, puedes establecer un Nombre para mostrar, que puede ser más expresivo y también es el campo que se mostrará a los usuarios

Después de crear el reino, ve a Configuración del reino (en el menú de la izquierda).

Ve a la parte inferior de la página hasta que puedas ver los Endpoints. Allí haz clic con el botón derecho en

Metadatos del proveedor de identidad SAML 2.0 y luego elige Copiar enlace.

La URL copiada debe ser algo parecido a esto 

Ojo: La Url de Metadatos del Proveedor de Identidad SAML 2.0 es la URL del Descriptor de tu Proveedor de Identidad Keycloak.

Ahora es el momento de establecer la configuración de nuestro Proveedor de Servicios en el Portal Marca Blanca.

Ve a nuestro sitio web e inicia sesión en tu cuenta de marca blanca. Una vez conectado, ve a la configuración de tu cuenta y elige la pestaña SSO.

Cuando te registras con un usuario de tu empresa en nuestra plataforma puedes elegir cómo puede acceder este usuario a la plataforma. Hay 2 escenarios diferentes posibles:

• El usuario inicia sesión como usuario de marca blanca 1:1
• El usuario puede iniciar sesión bajo diferentes usuarios de marca blanca 1:n

Para continuar con la configuración de la conexión SSO debes elegir primero un Tipo SSO

Para que entiendas los conceptos lo más rápidamente posible, utilizaremos un ejemplo durante este artículo. Hagamos las siguientes suposiciones:

• Los usuarios Adán, Eva y Steve trabajan en tu empresa y necesitan acceder a la Plataforma Marca Blanca.
• Estás utilizando Keycloak
  como Proveedor de Identidad (IDP) en tu empresa. Si no tienes Keycloak sino otro IDP no tienes por qué preocuparte.
  Puedes consultar nuestro publicación general sobre SSO.

Selecciona Usuario si quieres que un usuario de tu Proveedor de Identidades (="Usuario IDP") se asigne exactamente a un (1:1) usuario individual de marca blanca.

Usuario de marca blanca

Cuando un Usuario PDI inicie sesión por primera vez, se creará el Usuario Marca Blanca correspondiente. En el ejemplo anterior, el Usuario IDP Adán se creará como Usuario Marca Blanca Adán cuando inicie sesión por primera vez.

En este escenario, supongamos como ejemplo que la plataforma de Marca Blanca tiene un usuario para el departamento de Marketing y un usuario para el departamento de Servicio al cliente.

Selecciona Subcuenta si quieres que un usuario de tu Proveedor de Identidad (="Usuario IDP") se mapee a uno o más (1:n) usuarios de marca blanca.

En el ejemplo anterior, los usuarios IDP Adam y Eve pueden utilizar los Usuarios Marca Blanca Marketing y Servicio al Cliente. El usuario IDP Steve sólo puede utilizar el usuario de marca blanca Servicio al cliente

Antes de que se puedan utilizar a través de SSO asegúrate de que estos dos usuarios están creados en la Plataforma Marca Blanca creándolos a través del menú Usuarios de la parte izquierda y después Crear Usuario.

Después de la creación, la lista de Usuarios debería tener este aspecto:

Inspiración: Los Usuarios de Marca Blanca no tienen por qué estar basados en un departamento como Marketing o Atención al Cliente. Sólo utilizamos esto aquí como ejemplo.
También es bastante común que haya un Usuario Marca Blanca distinto para cada

• País (Austria, España, Italia, Brasil, etc.) y/o
• Marca (MarcaA, MarcaB, MarcaC, etc.) y/o
• Línea de productos (Zapatos, Camisas, Chaquetas, etc.)

El caso de uso puede ser diferente para cada empresa. Por tanto, piensa en cómo tendría más sentido para tu empresa.

Un Usuario IDP actuará entonces como un líder de equipo y podrá elegir bajo qué usuario de marca blanca quiere registrarse. Así, Adán y Eva pueden elegir si quieren registrarse como usuario de marca blanca Marketing o Servicio al cliente

Después de haber elegido el Tipo SSO necesitas introducir la URL del Descriptor IDP SSO de tu Proveedor de Identidades Keycloak. Esto es necesario para que podamos obtener información básica sobre cómo conectar y autenticar a tus usuarios con SAML 2.0.

Para ello sólo tienes que copiar en el campo la URL de metadatos del proveedor de identidad SAML 2.0 que has guardado antes.

Una vez que hayas introducido la URL del Descriptor IDP OSSO, las URL de los servicios se extraen de la URL del Descriptor y los campos de la URL del Servicio de Inicio de Sesión OSSO y la URL del Servicio de Cierre de Sesión OSSO se rellenan previamente.

Si no se muestra ninguna URL, introdúcela manualmente. La URL del Servicio de Cierre de Sesión OSL es opcional. Si se establece la URL, el usuario será redirigido a esta URL cuando cierre la sesión desde la plataforma del Código QR. Opcionalmente, también podrá cerrar la sesión desde su IDP

Para un sistema Keycloak la Url debería ser algo como esto 

Haz clic en el botón Conectar de la parte inferior para inicializar la conexión con tu Keycloak.

Conexión

Ahora necesitamos crear un Cliente en tu sistema Keycloak. Este cliente es el puente entre tu Keycloak y nuestro Proveedor de Servicios de Plataforma de Marca Blanca

Ahora vuelve a tu sistema Keycloak y entra en el reino con el que trabajabas antes (en nuestro ejemplo TuReinoEmpresa).

Haz clic en el menú Clientes y luego en Importar cliente (justo al lado del botón Crear cliente).

En la pantalla Importar cliente haz clic en Buscar y elige el archivo Descriptor XML que acabas de descargar anteriormente.

A continuación, el contenido del archivo XML Descriptor se carga en el área de texto Archivo de recursos y el ID de cliente se establece automáticamente.

Si lo deseas, puedes dar un nombre opcional al Cliente. En nuestro ejemplo lo llamaremos Plataforma de Código QR.

Haz clic en Guardar para guardar el nuevo cliente.

A continuación, tenemos que configurar nuestro Mapeador de Salidas en Keycloak para poder transferir campos como el nombre, los apellidos y el correo electrónico, así como los roles de los usuarios.

En el Cliente que acabas de crear (https://auth.webapp-portal.com/xxx) haz clic en la pestaña Ámbitos del cliente.

Ahora deberías ver un ámbito dedicado y un ámbito de lista de roles SMS.

En el ámbito Dedicado ya ves la lista de campos que nuestro Proveedor de Servicios necesita de tu Proveedor de Identidad Keycloak (gracias al Descriptor XML que subimos antes).

Ahora sólo tenemos que configurar el mapeo para ello. Para ello vamos a empezar por el nombre. Para ello haz clic en nombre en la columna Nombre.

Ahora haz clic en el desplegable Atributo de usuario y elige la entrada nombre. Haz clic en Guardar.

A continuación, haz lo mismo con el apellido.

Ahora, haz lo mismo para el correo electrónico.

Dado que los Mapeadores en el ámbito Dedicado se crearon automáticamente, debido a la carga del Descriptor XML, los Nombres de Atributos SAML ya coinciden con las entradas en el Mapeo de Entrada IDP SSO en nuestro Proveedor de Servicios. Por lo tanto, no es necesaria ninguna configuración adicional en el Proveedor de Servicios de la Plataforma de Marca Blanca en relación con el mapeo.

Si quieres utilizar el método Subcuenta (1:n) para crear usuarios en la Plataforma de Marca Blanca (del que ya hemos hablado) o quieres utilizar SSO para Administradores y Gestores, tendrás que configurar los Roles IDP para ello.

Puedes encontrar la pantalla necesaria siguiendo los siguientes pasos:

• Haz clic en Clientes en el menú de la izquierda
• Haz clic en el Cliente que acabas de crear - en nuestro ejemplo es QR Code Platform
• Haz clic en el botón Crear rol para crear un rol nuevo
  

Si has seleccionado la Subcuenta de tipo SSO (1:n) necesitas proporcionar la información de qué Usuario IDP debe tener acceso a qué Usuario Marca Blanca.

Para ello necesitamos crear un Rol adicional para cada Usuario Marca Blanca en los roles del Cliente Keycloak. El nombre del rol debe ser idéntico al nombre del usuario Marca Blanca.

Tu usuario administrador puede iniciar sesión en nuestra plataforma de marca blanca directamente a través de un nombre de usuario y una contraseña por defecto. Sin embargo, también es posible utilizar SSO para iniciar sesión como administrador o gerente.

Para ese caso hay 2 Roles especiales disponibles: whitelabel_admin y whitelabel_manager

En nuestro ejemplo tenemos 2 usuarios en la organización que son un admin/manager. El usuario Juan debe ser un Administrador en el Portal de Etiqueta Blanca, por lo que necesita el Role whitelabel_admin, la usuaria Monica debe ser una Gestora, por lo que necesita el Role whitelabel_manager.

Para ello necesitamos crear dos Roles adicionales llamados whitelabel_admin y whitelabel_manager en Keycloak. Los nombres de los roles deben ser exactamente esos.

Después de configurarlo todo, es hora de añadir usuarios en Keycloak, para que puedan acceder a la Plataforma de Marca Blanca.

En el escenario SSO-Tipo "1:n" o si quieres dar a un usuario un rol de Administrador o Gestor haz lo siguiente.

En Keycloak haz clic en el menú Usuarios (a la izquierda), luego elige un Usuario (en nuestro ejemplo Adam), haz clic en la pestaña Mapeo de roles y haz clic en Asignar rol.

En el desplegable de la parte superior izquierda, selecciona Filtrar por clientes para ver sólo nuestros roles de cliente e introduce webapp-portal.com en el campo de búsqueda para ver sólo los roles relevantes.

webapp-portal.com

Dado que Adán debe poder acceder a los usuarios Marca Blanca Marketing y Servicio al Cliente en el Escenario 1:n selecciona Marketing y Servicio al Cliente para el usuario Adán. Luego haz clic en Asignar.

Por el contrario, el usuario John debería ser un Administrador de Marca Blanca. En ese caso elige el rol admin_marcablanca.

En el escenario SSO-Tipo "1:n" o si quieres dar a un grupo un rol de Admin o Manager haz lo siguiente.

En nuestro ejemplo queremos tener el comportamiento de que todos los que estén en el Departamento de Marketing (miembro del Grupo Departamento de Marketing) tengan acceso al Usuario Etiqueta Blanca Marketing.

Normalmente ya tendrás grupos para tus departamentos como Marketing y Atención al Cliente y tendrás Usuarios asignados a ellos. Para este ejemplo supondremos que no los tenemos y los crearemos ahora.

Introduce el nombre del Grupo, por ejemplo Departamento de Marketing, y haz clic en Crear.

Ahora nos aseguraremos de que todos los miembros del grupo Departamento de Marketing tengan asignado el Rol Marketing. Para ello, abre el grupo Departamento de Marketing y haz clic en Asignar rol

Puedes hacer lo mismo con un grupo ServicioCliente Departamento y también, por ejemplo, con un grupo Administrador de Marca Blanca o Administrador de Marca Blanca Grupo.

Después de configurar los Grupos es hora de asignar Usuarios a los Grupos.

Haz clic en el menú de la izquierda Grupo, elige el Departamento de Marketing y haz clic en Añadir miembro.

En la ventana emergente selecciona los usuarios que deben pertenecer al grupo, en nuestro ejemplo el usuario Adam debe pertenecer al grupo Departamento de Marketing, y luego haz clic en Añadir.

Ahora el usuario Adam, y todos los demás usuarios que se añadan al grupo Departamento de Marketing, tendrán acceso al Role Marketing y por tanto podrán acceder a la Etiqueta Blanca de Usuario Marketing.

En esta sección verás el aspecto de la cuenta de marca blanca tras el primer inicio de sesión de los usuarios para los 2 tipos diferentes de SSO.

En esta sección verás el aspecto de la cuenta de marca blanca tras el primer inicio de sesión de los usuarios para los 2 tipos diferentes de SSO

Cuando un usuario IDP se conecta por primera vez mediante SSO, se crea un usuario Marca Blanca con el mismo nombre. En el siguiente ejemplo puedes ver los 3 usuarios IDP Adam, Eve y Steve creados como usuarios Marca Blanca en la sección Usuario.

Si un usuario IDP inicia sesión en nuestra plataforma por primera vez, se crea una subcuenta con el rol SSO y los usuarios Marca Blanca correspondientes se asignan a esa subcuenta. Puedes ver las subcuentas en la sección Cuentas de la pestaña Subcuentas

La siguiente captura de pantalla muestra al usuario IDP Adam asignado a los usuarios de Marca Blanca Marketing y Servicio al cliente.

Servicio al cliente

Para depurar la comunicación SAML 2.0 entre tu proveedor de identidades (IDP) y nuestro proveedor de servicios (SP) puedes instalar el complemento de navegador SAML-tracer.

• Firefox
• Chrome

Después de abrir la ventana emergente SAML-tracer...

1. empieza con un proceso de inicio de sesión SSO
2. Verás que la lista de la parte superior de la ventana emergente se llena de peticiones HTTP.
3. Haz clic en la petición que está marcada como petición SAML en color naranja.
4. Elige la pestaña Resumen (o SAML para todos los detalles en formato XML). Puedes comprobar si los datos (por ejemplo, el rol) se han transferido correctamente. En este caso se ha transferido el rol whitelabel_admin. Esto es exactamente lo que necesitamos para que este usuario inicie sesión como administrador del portal de etiqueta blanca.