Este documento ha sido traducido utilizando tecnología de traducción automática. Si bien nos esforzamos por proporcionar traducciones precisas, no ofrecemos garantías sobre la integridad, precisión o confiabilidad del contenido traducido. En caso de discrepancia, la versión original en inglés prevalecerá y constituirá el texto autorizado.

Configurar Keycloak (SAML)

Si tu organización utiliza Keycloak Identity Provider (IdP) para la autenticación de usuarios, puedes configurar Rancher para permitir que tus usuarios inicien sesión utilizando sus credenciales de IdP.

Requisitos previos

  • Debes tener un Servidor IdP de Keycloak configurado.

  • En Keycloak, crea un nuevo cliente SAML, con la configuración que se indica a continuación. Consulta la documentación de Keycloak para obtener ayuda.

    Valor Valor

    Sign Documents

    ON 1

    Sign Assertions

    ON 1

    Todos los demás ON/OFF Ajustes

    OFF

    Client ID

    O bien https://yourRancherHostURL/v1-saml/keycloak/saml/metadata o el valor configurado en el Entry ID Field de la configuración de Keycloak de Rancher2

    Client Name

    (p.ej. rancher)

    Client Protocol

    SAML

    Valid Redirect URI

    https://yourRancherHostURL/v1-saml/keycloak/saml/acs

    1: Opcionalmente, puedes habilitar uno o ambos de estos ajustes. 2: Los metadatos SAML de Rancher no se generarán hasta que se configure y guarde un proveedor SAML.

    keycloak saml client configuration

  • En el nuevo cliente SAML, crea Mapeadores para exponer los campos de los usuarios

    • Añade todos los "Mapeadores de Protocolo Integrados"

      keycloak saml client builtin mappers

    • Crea un nuevo mapeador de "Lista de Grupos" para mapear el atributo de miembro a los grupos de un usuario

      keycloak saml client group mapper

Obteniendo los Metadatos del IdP

  • Keycloak 5 y anteriores

  • Keycloak 6-13

  • Keycloak 14+

Para obtener los metadatos del IdP, exporta un archivo metadata.xml desde tu cliente de Keycloak. Desde la pestaña Instalación, elige la opción de formato Descriptor IDPSSOMetadata SAML y descarga tu archivo.

  1. Desde la sección Configurar, haga clic en la pestaña Configuración del dominio.

  2. Haga clic en la pestaña General.

  3. Desde el campo Puntos finales, haga clic en Metadatos del Proveedor de Identidad SAML 2.0.

Verifique que los metadatos del IDP contengan los siguientes atributos:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Algunos navegadores, como Firefox, pueden renderizar/procesar el documento de tal manera que el contenido parezca haber sido modificado y algunos atributos parezcan estar ausentes. En esta situación, utilice los datos de respuesta en bruto que se pueden encontrar utilizando su navegador.

El siguiente es un proceso de ejemplo para Firefox, pero variará ligeramente para otros navegadores:

  1. Presione F12 para acceder a la consola de desarrollador.

  2. Haga clic en la pestaña Red.

  3. Desde la tabla, haga clic en la fila que contiene descriptor.

  4. Desde el panel de detalles, haga clic en la pestaña Respuesta.

  5. Copie los datos de respuesta en bruto.

El XML obtenido contiene EntitiesDescriptor como el elemento root. Rancher espera que el elemento root sea EntityDescriptor en lugar de EntitiesDescriptor. Así que, antes de pasar este XML a Rancher, siga estos pasos para ajustarlo:

  1. Copie todos los atributos de EntitiesDescriptor al EntityDescriptor que no estén presentes.

  2. Elimine la etiqueta <EntitiesDescriptor> del principio.

  3. Elimine el </EntitiesDescriptor> del final del XML.

Le quedará algo similar al siguiente ejemplo:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
....
</EntityDescriptor>

  1. Desde la sección Configurar, haga clic en la pestaña Configuración del Dominio.

  2. Haga clic en la pestaña General.

  3. Desde el campo Puntos finales, haga clic en Metadatos del Proveedor de Identidad SAML 2.0.

Verifique que los metadatos del IDP contengan los siguientes atributos:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Algunos navegadores, como Firefox, pueden renderizar/procesar el documento de tal manera que el contenido parezca haber sido modificado y algunos atributos parezcan estar ausentes. En esta situación, utilice los datos de respuesta en bruto que se pueden encontrar utilizando su navegador.

El siguiente es un proceso de ejemplo para Firefox, pero variará ligeramente para otros navegadores:

  1. Presione F12 para acceder a la consola de desarrollador.

  2. Haga clic en la pestaña Red.

  3. Desde la tabla, haga clic en la fila que contiene descriptor.

  4. Desde el panel de detalles, haga clic en la pestaña Respuesta.

  5. Copie los datos de respuesta en bruto.

Configurando Keycloak en Rancher

  1. En la esquina superior izquierda, haz clic en ☰ > Usuarios y Autenticación.

  2. En el menú de navegación de la izquierda, haz clic en Proveedor de Autenticación.

  3. Haga clic en Keycloak SAML.

  4. Complete el formulario Configurar Cuenta Keycloak. Para obtener ayuda con el llenado del formulario, consulta la referencia de configuración.

  5. Después de completar el formulario Configurar una Cuenta Keycloak, haga clic en Habilitar.

    Rancher te redirige a la página de inicio de sesión del IdP. Introduzca las credenciales que se utilizan para autenticar en Keycloak IdP y validar la configuración de Keycloak en Rancher.

    Es posible que tengas que desactivar tu bloqueador de ventanas emergentes para ver la página de inicio de sesión del IdP.

Resultado: Rancher está configurado para trabajar con Keycloak. Tus usuarios ahora pueden iniciar sesión en Rancher utilizando sus credenciales de Keycloak.

Advertencias del Proveedor SAML

  • Los usuarios y grupos no son validados cuando les asignas permisos en Rancher.

  • Al añadir usuarios, los IDs de usuario exactos (es decir, UID Field) deben ser introducidos correctamente. A medida que escribes el ID de usuario, no habrá búsqueda de otros IDs de usuario que puedan coincidir.

  • Al añadir grupos, debes seleccionar el grupo del menú desplegable que está al lado del cuadro de texto. Rancher asume que cualquier entrada del cuadro de texto es un usuario.

  • El menú desplegable de grupos muestra solo los grupos de los que eres miembro. Sin embargo, si tienes permisos de Administrador o permisos de Administrador restringidos, puedes unirte a un grupo del que no eres miembro.

Referencia de configuración

Campo Descripción

Campo Nombre para Mostrar

El atributo que contiene el nombre para mostrar de los usuarios.

Ejemplo: givenName

Campo Nombre de Usuario

El atributo que contiene el nombre de usuario/nombre de pila.

Ejemplo: email

Campo UID

Un atributo que es único para cada usuario.

Ejemplo: email

Campo Grupos

Haz entradas para gestionar la membresía de grupos.

Ejemplo: member

Campo de ID de entidad

El ID que debe configurarse como un ID de cliente en el cliente de Keycloak.

Por defecto: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata

Host de la API de Rancher

La URL de tu servidor Rancher.

Clave Privada / Certificado

Un par de clave/certificado para crear un shell seguro entre Rancher y tu IdP.

IDP-metadata

El archivo metadata.xml que exportaste desde tu servidor IdP.

Puede generar un par de clave/certificado utilizando un comando openssl. Por ejemplo:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

Anexo: Solución de problemas

Si experimenta problemas al probar la conexión con el servidor Keycloak, primero verifique la opción de configuración de su cliente SAML. También puedes inspeccionar los registros de Rancher para ayudar a identificar la causa del problema. Los registros de depuración pueden contener información más detallada sobre el error. Por favor, consulta Cómo puedo habilitar el registro de depuración en esta documentación.

No se le redirige a Keycloak.

Cuando haga clic en Autenticar con Keycloak, no se le redirige a su IdP.

  • Verifique la configuración de su cliente Keycloak.

  • Asegúrese de que Force Post Binding esté configurado en OFF.

Mensaje prohibido mostrado después del inicio de sesión en el IdP.

Se le redirige correctamente a la página de inicio de sesión de su IdP y puede introducir sus credenciales; sin embargo, recibe un mensaje de Forbidden posteriormente.

  • Revise el registro de borrar de Rancher.

  • Si el registro muestra ERROR: either the Response or Assertion must be signed, asegúrese de que Sign Documents o Sign assertions estén configurados en ON en su cliente de Keycloak.

HTTP 502 al intentar acceder a /v1-saml/keycloak/saml/metadata.

Esto suele deberse a que los metadatos no se crean hasta que se configura un proveedor SAML. Intente configurar y guardar Keycloak como su proveedor SAML y, a continuación, acceda a los metadatos.

Error de Keycloak: "Lo sentimos, no se pudo procesar la respuesta"

  • Revise su registro de Keycloak.

  • Si el registro muestra failed: org.keycloak.common.VerificationException: Client does not have a public key, establezca Encrypt Assertions en OFF en su cliente de Keycloak.

Error de Keycloak: "Lo sentimos, solicitante no válido"

  • Revise su registro de Keycloak.

  • Si el registro muestra request validation failed: org.keycloak.common.VerificationException: SigAlg was null, establezca Client Signature Required en OFF en su cliente de Keycloak.

Popularidad de la comunidad CNI

Configuración de Cierre de Sesión Único SAML (SLO)

Rancher supports the ability to configure SAML SLO. Options include logging out of the Rancher application only, logging out of Rancher and registered applications tied to the external authentication provider, or a prompt asking the user to choose between the previous options. The steps below outline configuration from the application GUI:

The Log Out behavior configuration section only appears if the SAML authentication provider allows for SAML SLO.

  1. Sign in to Rancher using a standard user or an administrator role to configure SAML SLO.

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Under the section Log Out behavior, choose the appropriate SLO setting as described below:

    Setting Description

    Log out of Rancher and not authentication provider

    Choosing this option will only logout the Rancher application and not external authentication providers.

    Log out of Rancher and authentication provider (includes all other applications registered with authentication provider)

    Choosing this option will logout Rancher and all external authentication providers along with any registered applications linked to the provider.

    Allow the user to choose one of the above in an additional log out step

    Choosing this option presents users with a choice of logout method as described above.

Permisos de grupo SAML y OpenLDAP

When you configure a SAML authentication provider backed by OpenLDAP, the SAML response might return only a subset of the groups that a user belongs to. The exact groups returned depend on the configuration of your external authentication provider.

Rancher assigns user permissions based strictly on the groups provided in the SAML response.

Even if you can search for and view specific OpenLDAP groups in the Rancher UI, you cannot use them to assign permissions if they are missing from the SAML response.

To assign permissions successfully, verify that your SAML authentication provider is configured to return all necessary OpenLDAP groups.