Cómo utilizar Keycloak para el inicio de sesión SSO con Couchbase Capella

KeycloakKeycloak, una solución de código abierto de inicio de sesión único (SSO) y gestión de identidades, ofrece capacidades de integración con varias aplicaciones cliente. En este tutorial, exploraremos el proceso de integración de un cliente SAML (Security Assertion Markup Language) con Keycloak, permitiendo una autenticación de usuario cómoda y segura.

Es importante tener en cuenta que Keycloak no está probado ni validado por Couchbase. Couchbase proporciona instrucciones y soporte para Microsoft Azure AD, Okta, Ping Identity, CyberArk, Google Workspace y OneLogin. 

Demostraremos cómo integrar la autenticación SAML utilizando un proveedor SAML genérico, en este caso Keycloak. Aunque se puede utilizar cualquier proveedor SAML, recomendamos encarecidamente utilizar uno de nuestros servicios compatibles para una compatibilidad óptima y una experiencia de integración perfecta.

Requisitos previos

• • Asumo que tienes una instancia de Keycloak funcionando.
  • Tienes acceso a Capella como administrador de la Organización
  • SSO ha sido activado para su inquilino

Paso 1: Configurar Keycloak

Está fuera del alcance de este tutorial explicar cómo desplegar Keycloak como Proveedor de Identidad. Asumo que ya dispone de una instancia de Keycloak en funcionamiento y lista para ser utilizada.

Crear un reino

Cree un nuevo dominio en Keycloak para gestionar la configuración de su cliente SAML. En nuestro ejemplo, llamaremos a este dominio "acme".

Una vez creado el dominio, tenemos que guardar la clave pública. La forma más sencilla de hacerlo es abriendo el endpoint SAML Metadata. 

Obtener la configuración SAML

Haga clic en Configuración del dominio en la parte izquierda. Se abrirá la página de configuración del dominio. En la parte inferior de esta página, hay dos puntos finales de metadatos. 

Debe hacer clic en el botón Metadatos del proveedor de identidad SAML 2.0 enlace. El XML contiene los metadatos SAML que necesitará cuando cree su configuración Capella SSO. 

Enlace SAML HTTP-POST:

El certificado X.509:

Anótelos, ya que los necesitaremos en los pasos siguientes.

Paso 2: Crear un dominio en Capella

En este paso, crearemos un dominio Capella. Para ello, debemos copiar el certificado que guardamos en el primer paso en la carpeta Campo Certificado de firma SAML. También tenemos que copiar la URL de enlace HTTP_POST en el archivo URL del punto final de inicio de sesión campo.

El Algoritmo de Firma y el Algoritmo de Digesto deben ser los mismos que por defecto.

Asegúrese de que el campo SAML Protocol Binding está configurado como HTTP-POST:

En este punto ya está listo para crear el reino. 

Paso 3: Crear un cliente SAML Keycloak

Mostrar información de Capella Realm

En este punto, hemos creado el Capella Realm. Ahora, estamos listos para crear un cliente SAML en Keycloak.

En primer lugar, necesitamos información sobre el dominio de Capella. Haga clic en el nombre del dominio recién creado en Capella para mostrar la información del dominio.

Necesitaremos copiar varios datos de esta pantalla en Keycloak durante el proceso de creación del cliente. Tome nota de los siguientes campos.

• • Nombre del reino
  • Entidad ID
  • URL de devolución de llamada
  • Certificado de firma

Crear el cliente SAML Keycloak

Abra la consola de administración de Keycloak y seleccione el dominio que creó anteriormente. En la parte izquierda de la navegación, haga clic en Clientes.

En esta pantalla, pulse Crear cliente:

Copie el EntityID de Capella y pégalo en el campo ID de cliente de keycloak. Puede utilizar cualquier nombre que desee en el campo Nombre campo. 

Cuando esté listo, haga clic en el botón Siguiente. En esta pantalla, debe introducir la URL de inicio y las URI de redirección, como se muestra en la captura de pantalla:

El nuevo cliente SAML se creará en Keycloak cuando haga clic en el botón Guardar botón.

Configurar el cliente SAML de Keycloak

Debe abrir el cliente SAML que ha creado y hacer clic en el botón Avanzado tab. Eso te llevará a una pantalla como esta:

En esta pantalla, sólo tiene que rellenar los campos URL de enlace POST del servicio consumidor de aserciones. Debe copiar la URL de devolución de llamada de la página Realm de Capella e introducirla en este campo.

Importar firmas de clientes

Por defecto Se requiere la firma del cliente está habilitado en Keycloak. En ese caso Keycloak validará la petición SAML. Para ello, necesitamos guardar la clave pública SAML de Capella e importarla a Keycloak. 

Primero necesitamos guardar el Certificado desde Capella. Abra su página de configuración SSO en Capella. 

Abra la URL mostrada como Certificado de firma https://couchbase-capella.us.auth0.com/pem?cert=connection en una nueva pestaña. Esto activará una descarga. El archivo se llamará couchbase-capella.pem. Este certificado se utiliza para verificar la firma en la aserción SAML que se envía a Keycloak. No es el mismo que el certificado de seguridad de la base de datos Couchbase.

Ahora necesitas entrar de nuevo en Keycloak y abrir el cliente que creaste antes. Vaya a la sección Claves ficha. 

• • Haga clic en el Clave de importación botón.
  • Seleccione Certificado PEM en el menú Formato de archivo desplegable. 
  • Haga clic en Examinar para seleccionar el archivo y busque el archivo que acaba de guardar en Capella.

• • Haga clic en Importar para cargar el certificado de Capella en Keycloak

Paso 4: Configurar mapeadores SAML

Ahora el cliente SAML está listo. En el siguiente paso configuraremos los mapeadores SAML necesarios que permitirán a Capella leer los detalles del usuario desde el Assertion cuando el usuario esté iniciando sesión.

Abra el cliente SAML que acabamos de crear y haga clic en el botón Ámbitos de clientes ficha:

Deberías ver un ámbito de cliente con el nombre de tu id de cliente y un guión y dedicado. Tienes que hacer clic en ese enlace para añadir mapeadores personalizados.

Una vez que haga clic en ese botón, debería ver la siguiente pantalla:

Añadir el mapeador de apellidos

• • Haga clic en el botón configurar un nuevo mapeador botón
  • Seleccione Propiedad de usuario en la lista de mapeadores.

• • Rellene el formulario con los siguientes valores:
    Nombre: Apellido X500
    Propiedad: apellido
    Nombre amistoso: apellido
    Nombre del atributo SAML: apellido
    Atributo SAML NameFormat:  Sin especificar
    

Haga clic en guardar. Una vez que vea el mensaje de confirmación, deberá hacer clic en el botón Visores específicos para añadir el siguiente mapeador.

Ahora estamos listos para añadir el siguiente mapeador.

Añadir el mapeador firstName

• • Haga clic en el botón Añadir mapeador  y seleccione Por configuración. 
  • Seleccione Propiedad de usuario en la lista de mapeadores.

• • Rellene el formulario con los siguientes valores:
    Nombre: X500 givenName
    PropiedadNombre
    Nombre amistoso: givenName
    Nombre del atributo SAMLNombre
    Atributo SAML NameFormat:  Sin especificar
    

Haga clic en guardar. Una vez que vea el mensaje de confirmación (Mapeo creado correctamente), deberá hacer clic en el botón Visores específicos para añadir el siguiente mapeador.

Ahora estamos listos para añadir el mapeador final.

Añadir el mapeador de correo electrónico

• • Haga clic en el botón Añadir mapeador  y seleccione Por configuración. 
  • Seleccione Propiedad de usuario en la lista de mapeadores.

• • Rellene el formulario con los siguientes valores:
    Nombre: Correo electrónico X500
    Propiedad: correo electrónico
    Nombre amistoso: correo electrónico
    Nombre del atributo SAML: correo electrónico
    Atributo SAML NameFormat:  Sin especificar

Haga clic en guardar. Una vez que vea el mensaje de confirmación, deberá hacer clic en el botón Visores específicos para ver la lista completa de mapeadores. En este punto deberías ver a los tres.

Paso 5: Probar la integración

Para comenzar las pruebas, necesita al menos un usuario en su dominio. Puede utilizar usuarios existentes o crear un usuario sólo para probar la integración. Asegúrese también de haber cerrado la sesión en Capella antes de iniciar las pruebas.

• • Abrir https://cloud.couchbase.com 

• • Haga clic en Utilizar Inicio de sesión único
  • Introduzca el nombre de su dominio Capella SSO

Una vez que introduzca el nombre de su inquilino, será redirigido a su Keycloak. Deberá utilizar su usuario y credencial de prueba para iniciar sesión. Al final del flujo de inicio de sesión, habrá iniciado sesión en Capella. 

Nota: Capella utiliza el aprovisionamiento de usuarios JIT. Capella creará un usuario automáticamente la primera vez que inicie sesión con un usuario a través de su proveedor de identidad.

Conclusión

La integración de un cliente SAML con Keycloak le permite aprovechar las potentes características de gestión de identidades de Keycloak, permitiendo la funcionalidad de inicio de sesión único en Capella. Siguiendo la guía paso a paso proporcionada en este blog, ahora debería tener el conocimiento y las herramientas necesarias para integrar con éxito Capella con Keycloak, garantizando una autenticación de usuario segura y una experiencia de usuario optimizada.