Cómo configurar la autenticación SSO basada en SAML con Keycloak

En este artículo, proporcionaremos una guía paso a paso para configurar la autenticación de inicio de sesión único (SSO) basada en SAML en su instancia de Nextcloud.

El inicio de sesión único es un paso importante para mejorar la experiencia del usuario si ejecuta Nextcloud como una aplicación entre otras que tienen diferentes propósitos, por ejemplo, un sistema CRM o un sistema de soporte.

Introducción

En este artículo, proporcionaremos una guía paso a paso para configurar la autenticación de inicio de sesión único (SSO) basada en SAML en su instancia de Nextcloud.

El inicio de sesión único es un paso importante para mejorar la experiencia del usuario si ejecuta Nextcloud como una aplicación entre otras que tienen diferentes propósitos, por ejemplo, un sistema CRM o un sistema de soporte.

Las ventajas son evidentes tanto para el operador de la plataforma, que dispone de un punto central para gestionar las identidades de los usuarios, la autenticación y, en cierta medida, la autorización; como para el usuario, que no tendría que enfrentarse al problema de gestionar varias contraseñas, evitando así la típica mala elección de establecer la misma contraseña (simple) para todos los servicios digitales a los que tiene derecho a acceder.

A partir de ahora, en este tutorial, también nos referiremos a Keycloak como el proveedor de identidad y a Nextclod como el proveedor de servicio, retomando así la nomenclatura estándar en una configuración de SSO en la que diferentes proveedores de servicio delegan la autenticación en un único proveedor de identidad centralizado.

Nextcloud admite la autenticación basada en SAML gracias a una aplicación oficialmente compatible, Autenticación SSO & SAML, que garantiza la compatibilidad con las versiones recientes de la plataforma, ofrece un panel de configuración gráfico en el navegador y algunas funciones avanzadas, como el filtrado basado en roles y el manejo de respuestas firmadas y/o cifradas del proveedor de identidad. Nextcloud también admite la autenticación basada en OpenID, pero su configuración no entra en el ámbito de este artículo.

En este tutorial, el proveedor de identidad es Keycloak, que hemos elegido porque su uso está muy extendido y es de código abierto.

Entorno de trabajo

El procedimiento descrito en este tutorial se ha probado en un entorno de software con las versiones indicadas en la tabla, en una red de área local y sin proxies inversos en el medio, lo que significa que los certificados TLS se gestionan localmente en los sistemas.

Si quieres probar el tutorial, necesitarás usuarios administrativos tanto para la instancia de Keycloak como para la de Nextcloud.

Resumen

A continuación, describimos el procedimiento para que puedas entender a nivel general lo que vamos a hacer:

1. Configuración del proveedor de identidad: crearemos un dominio y obtendremos un parámetro que necesitamos para la configuración del proveedor de servicios.
2. Configuración del proveedor de servicios: instalaremos y configuraremos la aplicación llamada SSO & SAML Authentication.
3. Conclusión de la configuración del proveedor de identidad: importaremos la definición del cliente (es decir, el proveedor del servicio) y crearemos un Client Scope adecuado para un proveedor de servicios basado en Nextcloud.
4. Creación y configuración de un usuario de muestra en Keycloak, con sus roles.
5. Prueba de inicio de sesión en Nextcloud con ese usuario.
6. Indicaciones para la resolución de problemas.

Configuración del proveedor de identidad

En Keycloak, crea un nuevo dominio llamado localenv:

En la configuración del proveedor de servicios necesitaremos el certificado público X.509 de esta instancia de Keycloak. Podemos obtenerlo navegando a Realm Settings->Keys y haciendo clic en el botón Certificate en la línea correspondiente al Algorithm RS256 y en la columna Public Keys:

Copia toda la cadena, colócala entre las etiquetas -----BEGIN CERTIFICATE---- y -----END CERTIFICATE---- y guárdala para usarla más adelante.

Configuración del proveedor de servicio

En Nextcloud, instala la aplicación Autenticación SSO & SAML. Puedes hacerlo desde la interfaz web en la tienda de aplicaciones, con un usuario de administración:

O desde la línea de comandos, con occ:

$ occ enable:user_saml
user_saml 6.5.0 enabled

Ve a la página de configuración de Autenticación SSO y SAML (accesible a través de la navegación por la configuración de administrador o directamente en /settings/admin/saml) y rellena los campos con los valores especificados en la siguiente tabla:

En este punto, deberías poder descargar el archivo de metadatos, un archivo XML que importarás en Keycloak como cliente en el dominio localenv.

Configuración del proveedor de identidad

Importación y configuración del cliente

En la interfaz de usuario web de Keycloak, importa el cliente utilizando el archivo metadata.xml exportado desde la instancia de Nextcloud.
Navega a Clients->Import Client y selecciona para cargar el archivo XML que creaste anteriormente. La mayoría de los campos se rellenarán automáticamente, pero también puedes proporcionar Name y Description si lo deseas. Una vez terminado, haz clic en Save.

El nuevo Client debería aparecer ahora en la lista de Clients del dominio:

Atributos y Client Scope

Keycloak te da la posibilidad de personalizar qué atributos envía cuando un cliente (es decir, un proveedor de servicio al que se le proporciona autenticación) solicita autenticación para un usuario. En este tutorial, teniendo en cuenta la naturaleza de Nextcloud como proveedor de servicio, tendríamos que enviar los siguientes atributos:

• username: se utilizará como nombre de cuenta en Nextcloud
• email: se utiliza para almacenar la dirección de correo electrónico principal del usuario en Nextcloud
• quota: se utiliza para establecer la cuota de almacenamiento del usuario en Nextcloud
• firstname, se utiliza en el nombre para mostrar en Nextcloud
• lastname, se utiliza en el nombre para mostrar en Nextcloud

La implementación de esta configuración en Keycloak se realiza mediante la creación de un Client Scope con los atributos anteriores y la asignación de este Client Scope al cliente definido para el proveedor de servicios.

Aunque hay otros atributos que Nextcloud puede leer de la respuesta del IdP, están fuera del alcance de este tutorial.

Definición del atributo quota

Entre los atributos que queremos que Keycloak incluya en la respuesta a la solicitud de autenticación de Nextcloud, el único que no está predefinido es «cuota». Así que tendremos que definirlo.

Ve a Realm settings->User profile, luego Create attribute. Rellena los valores y haz clic en Save.

Una vez guardado, deberías ver la cuota en la lista de atributos definidos para el dominio:

Ahora, define un nuevo Client Scope, llamado nextcloud-user, navegando a Manage-Client->Scopes. Rellena los parámetros (el tipo debe ser SAML) y, a continuación, Save:

Una vez guardado, deberías ver el Client Scope nextcloud-user en la lista de Client Scopes definidos en el dominio localenv:

Ahora es el momento de definir en el Client Scope llamado nextcloud-user, los mappers, es decir, los atributos que se incluirán en las respuestas de autenticación para los clientes que tengan habilitado este Client Scope (aún no lo hemos habilitado para nuestro cliente, lo haremos más adelante).

Tus mappers en el Client Scope nextcloud-user se verán como en la siguiente tabla:

Ten en cuenta que lastname, email y firstname se definen a partir de mappers predefinidos mientras que quota se define como User Attribute, no como User Property como los demás.

Como ejemplo, en esta captura de pantalla puedes comprobar la definición de username:

Es hora de añadir el Client Scope nextcloud-user al Client que creamos para la instancia de Nextcloud. En Manage->Clients, haz clic en el Client llamado nc.localenv.com y luego ve a la pestaña Client scopes. Puedes añadir el Client Scope nextcloud-user haciendo clic en Add Client Scope y seleccionándolo.

Por último, también puedes cambiar el mapper para que el role_list de Client Scope tenga el nombre del atributo que coincida con el que espera la instancia Nextcloud, es decir, roles.

Como se muestra en la siguiente captura de pantalla, ve a Manage->Client Scopes, selecciona role_list y, a continuación, ve a la pestaña Mappers. Haz clic en role list y modifícala como se muestra. Asegúrate de que Single Role Attribute esté activado.

Creación de usuario

Antes de crear un usuario, vamos a crear un rol, que es una propiedad que Nextcloud utiliza como grupo. Un rol asignado a un usuario se convertirá en una pertenencia a un grupo para el usuario en Nextcloud.

Ve a Manage->Realm roles y añade uno o más roles. En nuestro ejemplo añadimos dos roles, nc-group-1 y nc-group-2:

Para crear un usuario, ve a Manage->Users y haz clic en Add user. Rellena todos los parámetros en los que hemos definido mappers de atributos, es decir, username, email, first name, last name y quota. No te olvides de definir una contraseña en la pestaña Credentials y de asignar al menos un rol al usuario en la pestaña Role mapping.

En nuestro ejemplo, el username es dwhite, el email Esta dirección de correo electrónico está siendo protegida contra los robots de spam. Necesita tener JavaScript habilitado para poder verlo., el first name es Daniel, el last name es White y la quota es 10 GB.

Ten en cuenta que hemos eliminado cualquier rol predefinido para el usuario. Esto no es obligatorio, pero te ayudará a mantener limpia tu instancia de Nextcloud, ya que todos los grupos a los que pertenecen los usuarios se crean (si aún no están definidos) cuando el usuario se autentica.

Probar el inicio de sesión

En este punto deberíamos poder iniciar sesión en Nextcloud con el usuario creado en Keycloak. Al abrir la url de Nextcloud, https://nc.localenv.com en nuestro caso, deberías ser redirigido automáticamente a la página de autenticación en Keycloak (a menos que hayas definido más de un backend de autenticación, en cuyo caso tendrás que elegir el que quieras utilizar).

Una vez que hayas iniciado sesión, puedes comprobar que todos los atributos definidos en Keycloak se han transferido correctamente a Nextcloud conectándote a la página de configuración de usuario:

Si no puedes conectarte (el error más común es Cuenta no aprovisionada) o si no encuentras algunos atributos que esperas, consulta la sección de resolución de problemas.

Resolución de problemas

Si recibes un mensaje de cuenta no aprovisionada u otros errores, la forma recomendada de solucionarlos es inspeccionar el registro de Nextcloud. Para ello, necesitarás el nivel de registro más detallado y una forma práctica de cambiar a ese nivel de registro solo con el fin de solucionar problemas con la autenticación SAML sería añadir la siguiente línea en tu archivo config.php:

'log.condition' => ['apps' => ['user_saml']]

Tras iniciar sesión correctamente, deberías ver las siguientes entradas en el registro (procesadas con grep y jq):

$ tail -f /var/www/nextcloud/data/nextcloud.log | grep saml | jq .message
"Attributes send by the IDP: {"lastname":["White"],"username":["dwhite"],"firstname":["Daniel"],"email":["Esta dirección de correo electrónico está siendo protegida contra los robots de spam. Necesita tener JavaScript habilitado para poder verlo."],"quota":["10GB"],"roles":["nc-group-1","nc-group-2"]}"
"Authentication successful"
"Email attribute content: Esta dirección de correo electrónico está siendo protegida contra los robots de spam. Necesita tener JavaScript habilitado para poder verlo."
"Display name attribute content: Daniel White"
"Quota attribute content: 10GB"
"Group attribute content: ["nc-group-1","nc-group-2"]"
"Updating attributes for existing user"
"Email address not updated"
"Display name not updated"
"Quota updated"
"Checking group SAML_nc-group-1 for removal"
"Checking group SAML_nc-group-2 for removal"
"Checking group SAML_nc-group-1 for addition"
"Checking group SAML_nc-group-2 for addition"
"Incoming groups updated"
"Session values set"
"User found, last login timestamp updated"

El sistema informa de qué atributos han sido enviados por el proveedor de identidad y si se han analizado correctamente y transformado en propiedades de usuario para el usuario en Nextcloud.

Conclusión

En este artículo hemos descrito un procedimiento paso a paso para configurar la autenticación de inicio de sesión único en Nextcloud utilizando un proveedor de identidad ampliamente conocido, Keycloak.

El objetivo del tutorial es ayudarte a empezar con la integración. Como has visto, la configuración requiere la definición de muchos parámetros, pero, por suerte, estos parámetros se pueden gestionar desde las interfaces gráficas de Nextcloud y Keycloak. Sin embargo, este procedimiento es solo el principio. Si estás interesado en implementar esto en producción en tu organización, hay muchos otros temas que deben entenderse y abordarse: alta disponibilidad, optimización de la experiencia de autenticación de usuario, política de definición de roles en Keycloak, implementación segura, filtrado basado en grupos, arquitectura de implementación y más.