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

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.

Conditions préalables

  • Vous devez avoir un Serveur IdP Keycloak configuré.

  • Dans Keycloak, créez un nouveau client SAML, avec les paramètres ci-dessous. Consultez la documentation Keycloak pour obtenir de l’aide.

    Paramètre Valeur

    Sign Documents

    ON 1

    Sign Assertions

    ON 1

    Tous les autres ON/OFF paramètres

    OFF

    Client ID

    Soit https://yourRancherHostURL/v1-saml/keycloak/saml/metadata soit la valeur configurée dans le Entry ID Field de la configuration Keycloak de Rancher2

    Client Name

    (e.g. rancher)

    Client Protocol

    SAML

    Valid Redirect URI

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

    1 : En option, vous pouvez activer l’un ou l’autre de ces paramètres, ou les deux. 2 : Les métadonnées SAML de Rancher ne seront pas générées tant qu’un fournisseur SAML n’est pas configuré et enregistré.

    keycloak saml client configuration

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

    • Ajoutez tous les "Mappers de protocole intégrés"

      keycloak saml client builtin mappers

    • Créez un nouveau mapper "Liste de groupes" pour mapper l’attribut membre aux groupes d’un utilisateur

      keycloak saml client group mapper

Obtenir les métadonnées de l’IdP

  • Keycloak 5 et versions antérieures

  • Keycloak 6-13

  • Keycloak 14+

Pour obtenir les métadonnées de l’IdP, exportez un fichier metadata.xml depuis votre client Keycloak. Depuis l’onglet Installation, choisissez l’option de format SAML Metadata IDPSSODescriptor et téléchargez votre fichier.

  1. Dans la section Configurer, cliquez sur l’onglet Paramètres du domaine Kerberos.

  2. Cliquez sur l’onglet Général.

  3. Dans le champ Points de terminaison, cliquez sur Métadonnées du fournisseur d’identité SAML 2.0.

Vérifiez que les métadonnées de l’IDP contiennent les attributs suivants :

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#"

Certains navigateurs, comme Firefox, peuvent rendre/traiter le document de manière à ce que le contenu semble avoir été modifié, et certains attributs semblent manquer. Dans cette situation, utilisez les données de réponse brutes que vous pouvez trouver en utilisant votre navigateur.

Le processus suivant est un exemple pour Firefox, mais variera légèrement pour d’autres navigateurs :

  1. Appuyez sur F12 pour accéder à la console de développement.

  2. Cliquez sur l’onglet Réseau.

  3. Dans le tableau, cliquez sur la ligne contenant descriptor.

  4. Dans le panneau des détails, cliquez sur l’onglet Réponse.

  5. Copiez les données de réponse brutes.

Le XML obtenu contient EntitiesDescriptor comme élément racine. Rancher s’attend à ce que l’élément racine soit EntityDescriptor plutôt que EntitiesDescriptor. Donc, avant de transmettre ce XML à Rancher, suivez ces étapes pour l’ajuster :

  1. Copiez tous les attributs de EntitiesDescriptor vers le EntityDescriptor qui ne sont pas présents.

  2. Supprimez la balise <EntitiesDescriptor> du début.

  3. Supprimez le </EntitiesDescriptor> de la fin du xml.

Il vous reste quelque chose de similaire à l’exemple ci-dessous :

<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. Dans la section Configurer, cliquez sur l’onglet Paramètres du domaine Kerberos.

  2. Cliquez sur l’onglet Général.

  3. Dans le champ Points de terminaison, cliquez sur Métadonnées du fournisseur d’identité SAML 2.0.

Vérifiez que les métadonnées de l’IDP contiennent les attributs suivants :

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#"

Certains navigateurs, comme Firefox, peuvent rendre/traiter le document de manière à ce que le contenu semble avoir été modifié, et certains attributs semblent manquer. Dans cette situation, utilisez les données de réponse brutes que vous pouvez trouver en utilisant votre navigateur.

Le processus suivant est un exemple pour Firefox, mais variera légèrement pour d’autres navigateurs :

  1. Appuyez sur F12 pour accéder à la console de développement.

  2. Cliquez sur l’onglet Réseau.

  3. Dans le tableau, cliquez sur la ligne contenant descriptor.

  4. Dans le panneau des détails, cliquez sur l’onglet Réponse.

  5. Copiez les données de réponse brutes.

Configurer Keycloak dans Rancher

  1. Dans le coin supérieur gauche, cliquez sur ☰ > Utilisateurs et authentification.

  2. Dans le menu de navigation à gauche, cliquez sur Fournisseur d’authentification.

  3. Cliquez sur Keycloak SAML.

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

  5. Après avoir complété le formulaire Configurer un compte Keycloak, 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. Vos utilisateurs peuvent désormais se connecter à Rancher en utilisant leurs identifiants Keycloak.

Avertissements concernant le fournisseur SAML

  • Les utilisateurs et les groupes ne sont pas validés lorsque vous leur attribuez des autorisations dans Rancher.

  • Lors de l’ajout d’utilisateurs, les identifiants d’utilisateur exacts (c’est-à-dire UID Field) doivent être saisis correctement. Lorsque vous tapez l’identifiant de l’utilisateur, il n’y aura pas de recherche d’autres identifiants d’utilisateur pouvant correspondre.

  • Lors de l’ajout de groupes, vous devez sélectionner le groupe dans le menu déroulant à côté de la zone de texte. Rancher suppose que toute saisie dans la zone de texte est un utilisateur.

  • Le menu déroulant des groupes affiche uniquement les groupes dont vous êtes membre. Cependant, si vous avez des permissions d’administrateur ou des permissions d’administrateur restreintes, vous pouvez rejoindre un groupe dont vous n’êtes pas membre.

Référence de configuration :

Champ Description

Champ Nom d’affichage

L’attribut qui contient le nom d’affichage des utilisateurs.

Exemple : givenName

Champ Nom d’utilisateur

L’attribut qui contient le nom d’utilisateur/prénom.

Exemple : email

Champ UID

Un attribut qui est unique à chaque utilisateur.

Exemple : email

Champ Groupes

Créez des entrées pour gérer l’appartenance aux groupes.

Exemple : member

Champ ID d’entité

L’ID qui doit être configuré comme ID client dans le client Keycloak.

Par défaut : https://yourRancherHostURL/v1-saml/keycloak/saml/metadata

Hôte de l’API Rancher

L’URL de votre serveur Rancher.

Clé privée / Certificat

Une paire clé/certificat pour créer un shell sécurisé entre Rancher et votre IdP.

IDP-metadata

Le fichier metadata.xml que vous avez exporté depuis votre serveur IdP.

Vous pouvez générer une paire de clés/certificats en utilisant une commande openssl. Par exemple :

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

Annexe : Dépannage

Si vous rencontrez des problèmes lors du test de la connexion au serveur Keycloak, vérifiez d’abord l’option de configuration de votre client SAML. Vous pouvez également consulter les journaux de Rancher pour aider à identifier la cause du problème. 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.

Vous n’êtes pas redirigé vers Keycloak

Lorsque vous cliquez sur Authentifier avec Keycloak, vous n’êtes pas redirigé vers votre IdP.

  • Vérifiez la configuration de votre client Keycloak.

  • Assurez-vous que Force Post Binding est défini sur OFF.

Message interdit affiché après la connexion à l’IdP

Vous êtes correctement redirigé vers la page de connexion de votre IdP et vous pouvez entrer vos identifiants, cependant vous recevez un message Forbidden par la suite.

  • Vérifiez le journal de débogage de Rancher.

  • Si le journal affiche ERROR: either the Response or Assertion must be signed, assurez-vous que Sign Documents ou Sign assertions est défini sur ON dans votre client Keycloak.

HTTP 502 lors de l’accès à /v1-saml/keycloak/saml/metadata

Cela est généralement dû au fait que les métadonnées ne sont pas créées tant qu’un fournisseur SAML n’est pas configuré. Essayez de configurer et d’enregistrer Keycloak comme votre fournisseur SAML, puis accédez aux métadonnées.

Erreur Keycloak : "Nous sommes désolés, échec du traitement de la réponse"

  • Vérifiez votre journal Keycloak.

  • Si le journal affiche failed: org.keycloak.common.VerificationException: Client does not have a public key, définissez Encrypt Assertions sur OFF dans votre client Keycloak.

Erreur Keycloak : "Nous sommes désolés, demandeur invalide"

  • Vérifiez votre journal Keycloak.

  • Si le journal affiche request validation failed: org.keycloak.common.VerificationException: SigAlg was null, définissez Client Signature Required sur OFF dans votre client Keycloak.

Popularité de la communauté CNI

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

Permissions de groupe SAML et 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.