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

Si votre organisation utilise Keycloak Identity Provider (IdP) pour l’authentification des utilisateurs, vous pouvez configurer Rancher pour permettre à vos utilisateurs de se connecter en utilisant leurs identifiants IdP. Rancher prend en charge l’intégration avec Keycloak en utilisant le protocole OpenID Connect (OIDC) et le protocole SAML. Les deux implémentations sont fonctionnellement équivalentes lorsqu’elles sont utilisées avec Rancher. Cette page décrit le processus de configuration de Rancher pour fonctionner avec Keycloak en utilisant le protocole OIDC.

Si vous préférez utiliser Keycloak avec le protocole SAML à la place, référez-vous à cette page.

Si vous avez une configuration existante utilisant le protocole SAML et souhaitez passer au protocole OIDC, référez-vous à cette section.

Conditions préalables

  • Sur Rancher, Keycloak (SAML) est désactivé.

  • Vous devez avoir un Serveur IdP Keycloak configuré.

  • Suivez la documentation Keycloak pour créer un nouveau client OIDC avec les paramètres ci-dessous.

    Paramètre Valeur

    Client ID

    <client-id> (par exemple rancher)

    Name

    <client-name> (par exemple rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

  • Dans le nouveau client OIDC, créez Mappers pour exposer les champs des utilisateurs.

    1. Dans le menu de navigation, cliquez sur Clients.

    2. Cliquez sur l’onglet Liste des clients.

    3. Trouvez et cliquez sur le client que vous avez créé.

    4. Cliquez sur l’onglet Scopes du client.

    5. Trouvez et cliquez sur le lien étiqueté <client-name>-dedicated. Par exemple, si vous avez nommé votre client rancher, recherchez le lien nommé rancher-dedicated.

    6. Cliquez sur l’onglet Mappers.

    7. Cliquez sur Configurer un nouveau mapper. Si vous avez déjà des mappers existants configurés, cliquez sur la flèche à côté de Ajouter un mapper et sélectionnez Par configuration. Répétez ce processus et créez ces mappers :

      • Dans le tableau des mappages, sélectionnez Appartenance au groupe et configurez un nouveau "Mapper de groupes" avec les paramètres ci-dessous. Pour les paramètres non mentionnés, utilisez la valeur par défaut.

        Paramètre Valeur

        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

      • Dans le tableau des mappages, sélectionnez Audience et configurez un nouveau "Client Audience" avec les paramètres ci-dessous. Pour les paramètres non mentionnés, utilisez la valeur par défaut.

        Paramètre Valeur

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • Dans le tableau des mappages, sélectionnez Appartenance au groupe et configurez un nouveau "Chemin des groupes" avec les paramètres ci-dessous. Pour les paramètres non mentionnés, utilisez la valeur par défaut.

        Paramètre Valeur

        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

  • Ajoutez les mappages de rôles suivants à tous les utilisateurs ou groupes qui ont besoin de consulter les utilisateurs de Keycloak.

    • Utilisateurs

    • Groupes

    1. Dans le menu de navigation, cliquez sur Utilisateurs.

    2. Cliquez sur l’utilisateur auquel vous souhaitez ajouter des mappages de rôles.

    3. Cliquez sur l’onglet Mappage de rôle.

    4. Cliquez sur Assigner un rôle.

    5. Sélectionnez les rôles suivants :

      • query-users

      • query-groups

      • view-users

    6. Cliquez sur Assigner.

    1. Dans le menu de navigation, cliquez sur Groupes.

    2. Cliquez sur le groupe auquel vous souhaitez ajouter des mappages de rôles.

    3. Cliquez sur l’onglet Mappage de rôle.

    4. Cliquez sur Assigner un rôle.

    5. Sélectionnez les rôles suivants :

      • query-users

      • query-groups

      • view-users

    6. Cliquez sur Assigner.

Configurer Keycloak dans Rancher

  1. Dans 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 Keycloak (OIDC).

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

    Lors de la configuration de la section Points de terminaison en utilisant l’option Générer, Rancher inclut /auth comme partie du chemin de contexte dans les champs Émetteur et Point de terminaison d’authentification, ce qui n’est valide que pour Keycloak 16 ou antérieur. Vous devez configurer les points de terminaison en utilisant l’option Spécifier pour Keycloak 17 et les versions ultérieures, qui ont migré vers Quarkus.

  5. Après avoir complété le formulaire Configurer un compte Keycloak OIDC, cliquez sur Activer.

    Rancher vous redirige vers la page de connexion de l’IdP. Entrez les identifiants permettant de vous authentifier auprès de l’IdP Keycloak afin de valider la configuration de Keycloak dans Rancher.

    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 Keycloak en utilisant le protocole OIDC. Vos utilisateurs peuvent désormais se connecter à Rancher en utilisant leurs identifiants Keycloak.

Référence de configuration :

Champ Description

ID du client

Le Client ID de votre client Keycloak.

Secret du client

Le Secret généré de votre client Keycloak. Dans la console Keycloak, sélectionnez Clients, sélectionnez le client que vous avez créé, sélectionnez l’onglet Credentials et copiez la valeur du champ Secret.

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

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 remplacements manuels si incorrects.

URL de Keycloak

L’URL de votre serveur Keycloak.

Domaine Kerberos Keycloak

Le nom du domaine Kerberos dans lequel le client Keycloak a été créé.

URL de Rancher

L’URL de votre serveur Rancher.

Émetteur

L’URL de votre IdP.

Point de terminaison d’authentification

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

Migration de SAML vers OIDC

Cette section décrit le processus de transition de l’utilisation de Rancher avec Keycloak (SAML) vers Keycloak (OIDC).

  1. Reconfigurer Keycloak.

    1. Configurer un nouveau OpenID Connect client selon les Prérequis. Assurez-vous que les mêmes Valid Redirect URIs sont définis.

    2. Configurer des mappers pour le nouveau client selon les Prérequis.

  2. Avant de configurer Rancher pour utiliser Keycloak (OIDC), Keycloak (SAML) doit d’abord être désactivé.

    1. Dans 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 Keycloak (SAML).

    4. Cliquez sur Désactiver.

  3. Suivez les étapes dans Configurer Keycloak dans Rancher.

    Après la configuration, les autorisations des utilisateurs de Rancher doivent être réappliquées car elles ne sont pas migrées automatiquement.

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.

Annexe : Dépannage

Si vous rencontrez des problèmes lors du test de la connexion au serveur Keycloak, 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 à Keycloak sont précédées de [generic oidc] ou [keycloak oidc].

Vous n’êtes pas redirigé vers Keycloak

Lorsque vous remplissez le formulaire Configurer un compte Keycloak OIDC et cliquez sur Activer, vous n’êtes pas redirigé vers votre IdP.

Vérifiez la configuration de votre client Keycloak.

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

Dans le formulaire Configurer un compte OIDC Keycloak, changez Points de terminaison en Specify (advanced) et remplacez les valeurs Issuer et Auth Endpoint. Pour trouver les valeurs, allez dans la console Keycloak et sélectionnez Paramètres du domaine Kerberos, sélectionnez l’onglet Général, et cliquez sur Configuration du point de terminaison OpenID. La sortie JSON affiche les valeurs pour issuer et authorization_endpoint.

Erreur Keycloak : "grant_type invalide"

Dans certains cas, ce message d’erreur peut être trompeur et est causé par une mauvaise configuration du Valid Redirect URI.

Impossible de voir les groupes lors de l’attribution de rôles globaux.

Si vous utilisez un utilisateur qui ne fait partie d’aucun groupe pour la configuration initiale, vous ne pouvez pas rechercher de groupes lorsque vous essayez d’attribuer un rôle global. Pour résoudre ce problème, vous pouvez soit :

  1. Modifier manuellement l’objet authconfig/keycloakoidc pour activer la recherche de groupes.

    1. Sur le serveur Rancher :

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. Définissez groupSearchEnabled: true.

    3. Enregistrez vos modifications.

  2. Reconfigurez votre configuration OIDC Keycloak en utilisant un utilisateur qui est attribué à au moins un groupe dans Keycloak.

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'