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 OIDC genérico

El OIDC genérico permite a los usuarios iniciar sesión en Rancher utilizando sus credenciales de su cuenta existente en un Proveedor de Identidad OIDC (IdP). Rancher soporta la integración con el protocolo OIDC y el protocolo SAML. Ambas implementaciones son funcionalmente equivalentes cuando se utilizan con Rancher. Las siguientes instrucciones describen cómo crear un cliente OIDC y configurar Rancher para trabajar con tu proveedor de autenticación. Los usuarios pueden iniciar sesión en Rancher utilizando sus credenciales del IdP OIDC.

Requisitos previos

Proveedor de Identidad

En Rancher, el OIDC genérico está deshabilitado.

Consulta la documentación de tu IdP específico para completar los requisitos previos listados.

Cliente OIDC

En tu IdP, crea un nuevo cliente con la configuración a continuación:

Valor Valor

Client ID

(p.ej. rancher)

Name

(p.ej. rancher)

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URI

https://yourRancherHostURL/verify-auth

En el nuevo cliente OIDC, crea mapeadores para exponer los campos del usuario.

Las reclamaciones groups y full_group_path generadas por los mapeadores de Grupos y Ruta de Grupo, que creas dentro del cliente OIDC en tu Proveedor de Identidad, deben ser arreglos JSON, p.ej. "groups":["admins","devs","qa"] y "full_group_path":["/admins","/devs","/qa"].

  1. Crea un nuevo Groups Mapper con la configuración a continuación:

    Valor Valor

    Name

    Groups Mapper

    Mapper Type

    Group Membership

    Token Claim Name

    groups

    Add to ID token

    OFF

    Add to access token

    OFF

    Add to user info

    ON

  2. Crea un nuevo Client Audience con la configuración a continuación:

    Valor Valor

    Name

    Client Audience

    Mapper Type

    Audience

    Included Client Audience

    Add to access token

    ON

  3. Crea un nuevo Groups Path con la configuración a continuación.

    Valor Valor

    Name

    Group Path

    Mapper Type

    Group Membership

    Token Claim Name

    full_group_path

    Full group path

    ON

    Add to user info

    ON

Rancher utiliza el valor recibido en la reclamación "sub" para formar el PrincipalID, que es el identificador único en Rancher. Es importante hacer de este un valor que sea único e inmutable.

Configurando OIDC genérico en Rancher

  1. En la esquina superior izquierda de 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 OIDC genérico.

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

  5. Haz clic en Habilitar.

    Rancher te redirigirá a la página de inicio de sesión del IdP. Introduce tus credenciales del IdP para validar tu configuración de Rancher Keycloak.

    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 tu proveedor utilizando el protocolo OIDC. Tus usuarios ahora pueden iniciar sesión en Rancher utilizando sus credenciales del IdP.

Mapeo de Reclamaciones Personalizadas

El mapeo de reclamaciones personalizadas dentro de la configuración de OIDC genérico es compatible con las reclamaciones name, email y groups. Esto te permite mapear manualmente estas reclamaciones OIDC cuando tu IdP no utiliza nombres estándar en los tokens.

Cómo funciona una reclamación de grupos personalizada

Una reclamación de grupos personalizada influye en cómo funcionan los grupos de usuarios:

  • Si tanto la reclamación estándar OIDC groups como la reclamación de grupos personalizada están presentes en el token del usuario, la reclamación personalizada complementa la lista de grupos proporcionada por la reclamación estándar.

  • Si no hay una reclamación de grupos estándar en el token, los grupos listados en la reclamación personalizada formarán los únicos grupos del usuario.

No hay funcionalidad de búsqueda disponible para grupos provenientes de una reclamación personalizada. Para asignar un rol a uno de estos grupos, debes introducir manualmente el nombre exacto del grupo en el campo RBAC.

Configuración de reclamaciones personalizadas

Cuando estés en el formulario de Configurar una cuenta OIDC:

  1. Selecciona Añadir reclamaciones personalizadas.

  2. Añade tus reclamaciones personalizadas name, email o groups en el campo correspondiente Reclamaciones Personalizadas.

Por ejemplo, si tu IdP envía groups en una reclamación llamada custom_roles, introduce custom_roles en el campo Reclamación de Grupos Personalizados. Rancher luego complementa la reclamación estándar OIDC groups o busca esa reclamación específica al procesar el token del usuario.

Referencia de configuración

Campo Descripción

ID del cliente

El ID de cliente de tu cliente OIDC.

Secreto de cliente

El secreto generado de tu cliente OIDC.

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 OIDC.

seguros

Elige si usar los valores generados para los campos de URL de Rancher, Emisor y Punto de Autenticación o proporcionar sobrescrituras manuales si son incorrectos.

URL de Rancher

La URL de tu servidor Rancher.

Emisor

La URL de tu IdP. Si tu proveedor tiene el descubrimiento habilitado, Rancher utiliza la URL del Emisor para obtener todas las URLs requeridas.

Punto de Autenticación

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

Reclamaciones Personalizadas

Campo de Reclamación Personalizado Reclamación OIDC Predeterminada Descripción de Reclamación Personalizada

Reclamación de Nombre Personalizada

name

El nombre de la reclamación en el token OIDC que contiene el nombre completo o el nombre de visualización del usuario.

Reclamación de Correo Electrónico Personalizada

email

El nombre de la reclamación en el token OIDC que contiene la dirección de correo electrónico del usuario.

Reclamación de Grupos Personalizada

groups

El nombre de la reclamación en el token OIDC que contiene las membresías de grupos del usuario (utilizada para RBAC).

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.

Solución de problemas

Si experimentas problemas al probar la conexión con el servidor OIDC, 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 OIDC genérico están precedidas por [generic oidc] o [oidc].

No eres redirigido a tu proveedor de autenticación

Si completas el formulario Configurar una cuenta OIDC genérica y haces clic en Habilitar, y no eres redirigido a tu IdP, verifica la configuración de tu cliente OIDC.

Los Issuer y Auth Endpoint generados son incorrectos

Si los Issuer y Auth Endpoint se generan incorrectamente, abre el formulario Configurar una cuenta OIDC, cambia Puntos finales a Specify (advanced) y sobrescribe el valor de Issuer.

Error: "Invalid grant_type"

En algunos casos, el mensaje de error "Grant_type inválido" puede ser engañoso y en realidad es causado por configurar el Valid Redirect URI incorrectamente.

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'