Ce document a été traduit à l'aide d'une technologie de traduction automatique. Bien que nous nous efforcions de fournir des traductions exactes, nous ne fournissons aucune garantie quant à l'exhaustivité, l'exactitude ou la fiabilité du contenu traduit. En cas de divergence, la version originale anglaise prévaut et fait foi.

Configurer OIDC générique

L’OIDC générique permet aux utilisateurs de se connecter à Rancher en utilisant les identifiants de leur compte existant auprès d’un fournisseur d’identité OIDC (IdP). Rancher prend en charge l’intégration avec le protocole OIDC et le protocole SAML. Les deux implémentations sont fonctionnellement équivalentes lorsqu’elles sont utilisées avec Rancher. Les instructions suivantes décrivent comment créer un client OIDC et configurer Rancher pour fonctionner avec votre fournisseur d’authentification. Les utilisateurs peuvent alors se connecter à Rancher en utilisant leurs identifiants de l’IdP OIDC.

Conditions préalables

Fournisseur d’identité

Dans Rancher, l’OIDC générique est désactivé.

Consultez la documentation de votre IdP spécifique pour compléter les prérequis listés.

Client OIDC

Dans votre IdP, créez un nouveau client avec les paramètres ci-dessous :

Paramètre Valeur

Client ID

(e.g. rancher)

Name

(e.g. rancher)

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URI

https://yourRancherHostURL/verify-auth

Dans le nouveau client OIDC, créez des mappers pour exposer les champs de l’utilisateur.

Les revendications groups et full_group_path générées par les mappers Groupes et Chemin de Groupe, que vous créez dans le client OIDC de votre fournisseur d’identité, doivent être des tableaux JSON, par exemple "groups":["admins","devs","qa"] et "full_group_path":["/admins","/devs","/qa"].

  1. Créez un nouveau Groups Mapper avec les paramètres ci-dessous :

    Paramètre Valeur

    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. Créez un nouveau Client Audience avec les paramètres ci-dessous :

    Paramètre Valeur

    Name

    Client Audience

    Mapper Type

    Audience

    Included Client Audience

    Add to access token

    ON

  3. Créez un nouveau Groups Path avec les paramètres ci-dessous.

    Paramètre Valeur

    Name

    Group Path

    Mapper Type

    Group Membership

    Token Claim Name

    full_group_path

    Full group path

    ON

    Add to user info

    ON

Rancher utilise la valeur reçue dans la revendication "sub" pour former le PrincipalID qui est l’identifiant unique dans Rancher. Il est important de faire de cela une valeur qui soit unique et immuable.

Configuration de l’OIDC générique dans Rancher

  1. Dans le coin supérieur gauche de l’interface utilisateur de Rancher, cliquez sur ☰ > Utilisateurs et authentification.

  2. Dans la barre de navigation à gauche, cliquez sur Fournisseur d’authentification.

  3. Sélectionnez OIDC générique.

  4. Complétez le formulaire Configurer un compte OIDC. Pour obtenir de l’aide sur le remplissage du formulaire, consultez la référence de configuration.

  5. Cliquez sur Activer.

    Rancher vous redirigera vers la page de connexion de l’IdP. Entrez vos identifiants IdP pour valider votre configuration Rancher Keycloak.

    Vous devrez peut-être désactiver votre bloqueur de fenêtres contextuelles pour voir la page de connexion de l’IdP.

Résultat : Rancher est configuré pour fonctionner avec votre fournisseur en utilisant le protocole OIDC. Vos utilisateurs peuvent désormais se connecter à Rancher en utilisant leurs identifiants IdP.

Mapping de revendications personnalisé

Le mapping de revendications personnalisé dans la configuration OIDC générique est pris en charge pour les revendications name, email et groups. Cela vous permet de mapper manuellement ces revendications OIDC lorsque votre IdP n’utilise pas de noms standards dans les tokens.

Comment fonctionne une revendication de groupes personnalisée

Une revendication de groupes personnalisée influence le fonctionnement des groupes d’utilisateurs :

  • Si la revendication OIDC standard groups et la revendication de groupes personnalisée sont toutes deux présentes dans le jeton de l’utilisateur, la revendication personnalisée complète la liste des groupes fournie par la revendication standard.

  • S’il n’y a pas de revendication de groupes standard dans le jeton, les groupes listés dans la revendication personnalisée constitueront les seuls groupes de l’utilisateur.

Aucune fonctionnalité de recherche n’est disponible pour les groupes provenant d’une revendication personnalisée. Pour attribuer un rôle à l’un de ces groupes, vous devez entrer manuellement le nom exact du groupe dans le champ RBAC.

Configuration des revendications personnalisées

Lorsque vous êtes sur le formulaire Configurer un compte OIDC :

  1. Sélectionnez Ajouter des revendications personnalisées.

  2. Ajoutez vos revendications personnalisées name, email ou groups dans le champ approprié Revendications personnalisées.

Par exemple, si votre IdP envoie groups dans une revendication appelée custom_roles, entrez custom_roles dans le champ Revendication de groupes personnalisée. Rancher complète ensuite la revendication OIDC standard groups ou recherche cette revendication spécifique lors du traitement du jeton de l’utilisateur.

Référence de configuration :

Champ Description

ID du client

L’ID client de votre client OIDC.

Secret du client

Le secret généré de votre client OIDC.

Clé privée/Certificat

Une paire clé/certificat pour créer un shell sécurisé entre Rancher et votre IdP. Requis si HTTPS/SSL est activé sur votre serveur OIDC.

noeuds d’extrémité

Choisissez d’utiliser les valeurs générées pour les champs Rancher URL, Issue et Auth Endpoint ou de fournir des valeurs de remplacement manuelles si elles sont incorrectes.

URL de Rancher

L’URL de votre serveur Rancher.

Émetteur

L’URL de votre IdP. Si votre fournisseur a la découverte activée, Rancher utilise l’URL de l’émetteur pour récupérer toutes les URL requises.

Point de terminaison d’authentification

L’URL où les utilisateurs sont redirigés pour s’authentifier.

Revendications personnalisées

Champ de revendication personnalisée Revendication OIDC par défaut Description de la revendication personnalisée

Revendication de nom personnalisé

name

Le nom de la revendication dans le jeton OIDC qui contient le nom complet ou le nom d’affichage de l’utilisateur.

Revendication d’email personnalisée

email

Le nom de la revendication dans le jeton OIDC qui contient l’adresse email de l’utilisateur.

Revendication de groupes personnalisée

groups

Le nom de la revendication dans le jeton OIDC qui contient les appartenances aux groupes de l’utilisateur (utilisé pour RBAC).

Support OIDC pour l’extension 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.

Dépannage

Si vous rencontrez des problèmes lors du test de la connexion au serveur OIDC, vérifiez d’abord les options de configuration de votre client OIDC. Vous pouvez également inspecter les journaux de Rancher pour aider à identifier ce qui cause des problèmes. Les journaux de débogage peuvent contenir des informations plus détaillées sur l’erreur. Veuillez vous référer à Comment puis-je activer la journalisation de débogage dans cette documentation.

Toutes les entrées de journal liées à OIDC générique sont précédées de [generic oidc] ou [oidc].

Vous n’êtes pas redirigé vers votre fournisseur d’authentification.

Si vous remplissez le formulaire Configurer un compte OIDC générique et cliquez sur Activer, et que vous n’êtes pas redirigé vers votre IdP, vérifiez la configuration de votre client OIDC.

Les Issuer et Auth Endpoint générés sont incorrects

Si les Issuer et Auth Endpoint sont générés incorrectement, ouvrez le formulaire Configurer un compte OIDC, changez Points de terminaison en Specify (advanced) et remplacez la valeur de Issuer.

Erreur : "grant_type invalide"

Dans certains cas, le message d’erreur "grant_type invalide" peut être trompeur et est en réalité causé par une configuration incorrecte du Valid Redirect URI.

Configuration de la déconnexion unique 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'