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 (OIDC)

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. Rancher soporta la integración con Keycloak utilizando el protocolo OpenID Connect (OIDC) y el protocolo SAML. Ambas implementaciones son funcionalmente equivalentes cuando se utilizan con Rancher. Esta página describe el proceso para configurar Rancher para trabajar con Keycloak utilizando el protocolo OIDC.

Si prefieres utilizar Keycloak con el protocolo SAML en su lugar, consulta esta página.

Si tienes una configuración existente utilizando el protocolo SAML y deseas cambiar al protocolo OIDC, consulta esta sección.

Requisitos previos

  • En Rancher, Keycloak (SAML) está deshabilitado.

  • Debes tener un Servidor IdP de Keycloak configurado.

  • Sigue la documentación de Keycloak para crear un nuevo cliente OIDC con la configuración a continuación.

    Valor Valor

    Client ID

    <client-id> (p.ej. rancher)

    Name

    <client-name> (p.ej. rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

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

    1. En el menú de navegación, haz clic en Clientes.

    2. Haz clic en la pestaña Lista de clientes.

    3. Encuentra y haz clic en el cliente que creaste.

    4. Haz clic en la pestaña Ámbitos del cliente.

    5. Encuentra y haz clic en el enlace etiquetado como <client-name>-dedicated. Por ejemplo, si nombraste a tu cliente rancher, busca el enlace llamado rancher-dedicated.

    6. Haz clic en la pestaña Mapeadores.

    7. Haz clic en Configurar un nuevo mapeador. Si ya tienes mapeadores existentes configurados, haz clic en la flecha junto a Añadir mapeador y selecciona Por configuración. Repite este proceso y crea estos mapeadores:

      • Desde la tabla de mapeos, selecciona Pertinencia a grupos y configura un nuevo mapeador de grupos con los ajustes a continuación. Para los ajustes que no se mencionan, utiliza el valor por defecto.

        Valor Valor

        Name

        Groups Mapper

        Mapper Type

        Group Membership

        Token Claim Name

        groups

        Full group path

        OFF

        Add to ID token

        OFF

        Add to access token

        OFF

        Add to user info

        ON

      • Desde la tabla de mapeos, selecciona Audiencia y configura un nuevo "Audiencia del Cliente" con los ajustes a continuación. Para los ajustes que no se mencionan, utiliza el valor por defecto.

        Valor Valor

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • Desde la tabla de mapeos, selecciona Pertinencia a grupos y configura un nuevo "Ruta de Grupos" con los ajustes a continuación. Para los ajustes que no se mencionan, utiliza el valor por defecto.

        Valor Valor

        Name

        Group Path

        Mapper Type

        Group Membership

        Token Claim Name

        full_group_path

        Full group path

        ON

        Add to ID token

        ON

        Add to access token

        ON

        Add to user info

        ON

  • Añade los siguientes mapeos de roles a todos los usuarios o grupos que necesiten consultar los usuarios de Keycloak.

    • Usuarios

    • Grupos

    1. En el menú de navegación, haz clic en Usuarios.

    2. Haz clic en el usuario al que deseas añadir mapeos de roles.

    3. Haz clic en la pestaña Mapeo de roles.

    4. Haz clic en Asignar rol.

    5. Selecciona los siguientes roles:

      • consultar-usuarios

      • consultar-grupos

      • ver-usuarios

    6. Haz clic en Asignar.

    1. En el menú de navegación, haz clic en Grupos.

    2. Haz clic en el grupo al que deseas añadir mapeos de roles.

    3. Haz clic en la pestaña Mapeo de roles.

    4. Haz clic en Asignar rol.

    5. Selecciona los siguientes roles:

      • consultar-usuarios

      • consultar-grupos

      • ver-usuarios

    6. Haz clic en Asignar.

Configurando Keycloak en Rancher

  1. En la interfaz de Rancher, haz clic en ☰ > Usuarios y Autenticación.

  2. En la barra de navegación izquierda, haz clic en Proveedor de Autenticación.

  3. Selecciona Keycloak (OIDC).

  4. Completa el formulario Configurar una cuenta OIDC de Keycloak. Para obtener ayuda con el llenado del formulario, consulta la referencia de configuración.

    Al configurar la sección Endpoints utilizando la opción Generar, Rancher incluye /auth como parte de la ruta de contexto en los campos Emisor y Punto de Autenticación, que solo es válido para Keycloak 16 o anterior. Debes configurar los endpoints utilizando la opción Especificar para Keycloak 17 y versiones más recientes, que han migrado a Quarkus.

  5. Después de completar el formulario Configurar una cuenta OIDC de Keycloak, haz 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 necesites 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 utilizando el protocolo OIDC. Tus usuarios ahora pueden iniciar sesión en Rancher utilizando sus credenciales de Keycloak.

Referencia de configuración

Campo Descripción

ID del cliente

El Client ID de tu cliente de Keycloak.

Secreto del cliente

El Secret generado de tu cliente de Keycloak. En la consola de Keycloak, selecciona Clientes, selecciona el cliente que creaste, selecciona la pestaña Credenciales y copia el valor del campo Secret.

Clave Privada / Certificado

Un par de clave/certificado para crear un shell seguro entre Rancher y tu IdP. Requerido si HTTPS/SSL está habilitado en tu servidor de Keycloak.

seguros

Elige si usar los valores generados para los campos Rancher URL, Issue y Auth Endpoint o proporcionar sobrescrituras manuales si son incorrectos.

URL de Keycloak

La URL de tu servidor de Keycloak.

Dominio de Keycloak

El nombre del dominio en el que se creó el cliente de Keycloak.

URL de Rancher

La URL de tu servidor Rancher.

Emisor

La URL de tu IdP.

Endpoint de autenticación

La URL a la que se redirigen los usuarios para autenticarse.

Migrando de SAML a OIDC

Esta sección describe el proceso para hacer la transición de usar Rancher con Keycloak (SAML) a Keycloak (OIDC).

  1. Reconfigurar Keycloak.

    1. Configura un nuevo OpenID Connect cliente de acuerdo con los Requisitos previos. Asegúrate de que los mismos Valid Redirect URIs estén configurados.

    2. Configura los mapeadores para el nuevo cliente de acuerdo con los Requisitos previos.

  2. Antes de configurar Rancher para usar Keycloak (OIDC), primero debe deshabilitarse Keycloak (SAML).

    1. En la interfaz de Rancher, haz clic en ☰ > Usuarios y Autenticación.

    2. En la barra de navegación izquierda, haz clic en Proveedor de Autenticación.

    3. Selecciona Keycloak (SAML).

    4. Haz clic en Deshabilitar.

  3. Sigue los pasos en Configurando Keycloak en Rancher.

    Una vez completada la configuración, es necesario reaplicar los permisos de usuario de Rancher, ya que no se migran automáticamente.

Soporte OIDC para la Extensión PKCE

Rancher supports the Proof Key for Code Exchange (PKCE) extension (RFC 7636) for OIDC authentication providers. SHA-256 (S256) is the only supported PKCE verification method. To enable this feature, your authentication provider must use PKCE with S256 for authorization requests.

You can enable this feature by selecting Enable PKCE (S256) in your authentication provider configuration in Rancher. Enabling S256 PKCE token verification allows you to mitigate authorization code interception attacks during OIDC authentication flows.

Anexo: Solución de problemas

Si experimentas problemas al probar la conexión con el servidor Keycloak, primero verifica las opciones de configuración de tu cliente OIDC. También puedes inspeccionar los registros de Rancher para ayudar a identificar qué está causando los problemas. 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.

Todas las entradas de registro relacionadas con Keycloak están precedidas por [generic oidc] o [keycloak oidc].

No se le redirige a Keycloak.

Cuando llenas el formulario Configurar una cuenta OIDC de Keycloak y haces clic en Habilitar, no eres redirigido a tu IdP.

Verifique la configuración de su cliente Keycloak.

Los Issuer y Auth Endpoint generados son incorrectos

En el formulario Configurar una cuenta OIDC de Keycloak, cambia Endpoints a Specify (advanced) y sobrescribe los valores de Issuer y Auth Endpoint. Para encontrar los valores, ve a la consola de Keycloak y selecciona Configuración del dominio, selecciona la pestaña General y haz clic en Configuración del Endpoint de OpenID. La salida JSON muestra valores para issuer y authorization_endpoint.

Error de Keycloak: "Invalid grant_type"

En algunos casos, este mensaje de error puede ser engañoso y es causado por configurar el Valid Redirect URI incorrectamente.

No se pueden ver grupos al asignar roles globales.

Si utilizas un usuario que no forma parte de ningún grupo para la configuración, no podrás buscar grupos al intentar asignar un rol global. Para resolver esto, puedes hacer lo siguiente:

  1. Editar manualmente el objeto authconfig/keycloakoidc para habilitar la búsqueda de grupos.

    1. En el servidor Rancher:

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. Establece groupSearchEnabled: true.

    3. Guarde los cambios.

  2. Reconfigura tu configuración OIDC de Keycloak utilizando un usuario que esté asignado a al menos un grupo en Keycloak.

Configurar el cierre de sesión único OIDC (SLO)

Rancher supports the ability to configure OIDC Single Logout (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.

Prerequisites

Before configuring OIDC SLO, ensure the following is set up on your IdP:

  • SLO Support: The Log Out behavior configuration section only appears if your OIDC IdP allows for OIDC SLO.

  • Post-Logout Redirect URI: Your Rancher Server URL must be configured as an authorized post-logout redirect URI in your IdP’s OIDC client settings. This URL is used by the IdP to redirect a user back to Rancher after a successful external logout.

OIDC SLO Configuration

Configure the SLO settings when setting up or editing your OIDC authentication provider.

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

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

  3. In the left navigation menu, select 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.

  5. If you choose to log out of your IdP, provide an End Session Endpoint. Rancher uses this URL to initiate the external logout.

How to get the End Session Endpoint

The end_session_endpoint is one of the specific URLs published within a standardized JSON object containing the IdP’s metadata and is retrieved from the OIDC Discovery URL. To get the end_session_endpoint from the OIDC Discovery URL, follow these steps:

  1. Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).

  2. Send an HTTP GET request to the Discovery URL.

  3. In the JSON object, look for the key named end_session_endpoint and retrieve the URL.

    You can also use a curl command to retrieve end_session_endpoint:

    curl -s <ISSUER_URL>/.well-known/openid-configuration | jq '.end_session_endpoint'