Configurez la fédération LDAP ou Active Directory pour IBM Bob on-premises à l'aide de la ressource personnalisée BobIDP et de la commande bobctl configure-idp.

Utilise bobctl configure-idp pour connecter ton environnement LDAP ou Active Directory à Keycloak en tant que fournisseur de fédération d'utilisateurs. Tu peux effectuer cette configuration lors de l'installation ou à tout moment après le déploiement.

Avant de commencer

Avant de configurer la fédération LDAP, assurez-vous que les conditions suivantes sont remplies :

Le cluster OpenShift Container Platform (OCP) dispose d'une connectivité réseau vers le serveur LDAP sur le port approprié :

389 pour ldap://
636 pour ldaps://

Un compte de service (bind DN) avec accès en lecture à l'annuaire est disponible, ou le serveur LDAP est configuré pour autoriser les liaisons anonymes.

Si vous utilisez ldaps:// avec une autorité de certification (CA) privée ou signée en interne, procurez-vous le certificat CA du serveur LDAP au format PEM.

L'utilitaire en ligne de commande bobctl est installé, et oc est configuré et authentifié auprès du cluster cible.

Référence du fichier de configuration

Crée un fichier de configuration IDP à partir du modèle fourni avant d'enregistrer un fournisseur LDAP.

cp config-idp-template.yaml my-idp.yaml

Le fichier de configuration comporte deux sections : les champs de niveau supérieur qui s'appliquent à l'ensemble du déploiement, et une liste ldaps optionnelle où chaque entrée décrit un fournisseur de fédération LDAP.

Champs de niveau supérieur

Champ	Obligatoire	Description
`domains`	Oui	Liste des domaines de messagerie que Bob accepte lors de la connexion. La suppression d'un domaine le désenregistre ; les utilisateurs ayant ce domaine ne pourront plus se connecter.
`adminEmails`	Non	Liste des adresses e-mail des utilisateurs auxquels accorder l'accès administrateur Bob. L'opérateur met à jour le groupe Keycloak `bob-admins` et la base de données d'administration Bob de manière atomique.
`ldaps`	Non	Liste des configurations de fournisseurs de fédération LDAP. Omets entièrement pour les déploiements qui utilisent uniquement des utilisateurs Keycloak directs.

Champs obligatoires (par entrée de fournisseur LDAP)

Champ	Description
`name`	Un identifiant unique et descriptif pour le fournisseur LDAP. Chaque fournisseur configuré doit avoir un nom distinct.
`vendor`	Spécifie le type d'annuaire LDAP à intégrer. Valeurs prises en charge : `other` (OpenLDAP et compatible LDAPv3), `ad` (Microsoft Active Directory), `rhds` (Red Hat Directory Server), `tivoli` (IBM Security Directory Server), `edirectory` (NetIQ eDirectory).
`connectionUrl`	L'URL complète du serveur LDAP, comprenant le protocole (`ldap://` ou `ldaps://`), le nom d'hôte et le numéro de port.
`usersDn`	L'emplacement dans l'annuaire où les comptes utilisateurs sont stockés et à partir duquel les entrées d'utilisateurs sont recherchées et importées.
`usernameLDAPAttribute`	L'attribut d'annuaire que les utilisateurs fournissent comme nom d'utilisateur lors de l'authentification.
`rdnLDAPAttribute`	L'attribut d'annuaire utilisé pour identifier les entrées dans la structure de l'annuaire. Dans la plupart des configurations, il est identique à `usernameLDAPAttribute`.
`uuidLDAPAttribute`	Un attribut d'annuaire unique, stable et invariable utilisé pour identifier de manière permanente chaque compte utilisateur.
`userObjectClasses`	Une liste d'objectClass LDAP séparées par des virgules définissant les entrées d'annuaire reconnues et traitées comme des comptes utilisateurs.

Important :

Le champ domains est la seule façon de configurer le routage par domaine dans les déploiements on-premises. Ne configure pas les domaines via l'interface utilisateur d'administration de Bob car ce n'est pas la méthode correcte et peut entraîner des erreurs d'authentification.

Champs facultatifs (par entrée de fournisseur LDAP)

Champ	Description
`bindDn`	Le DN du compte de service utilisé pour s'authentifier et se connecter à l'annuaire. Peut être omis si l'annuaire autorise les liaisons anonymes.
`bindPasswordSecret`	Nom d'un Secret pré-existant contenant le mot de passe du compte de liaison. Doit être créé dans le namespace de l'instance avant d'exécuter `bobctl configure-idp`.
`useTruststoreSpi`	Spécifie quand le certificat CA LDAP est utilisé pour la validation du serveur. Valeurs : `always` (par défaut, pour les certificats CA privés ou internes), `ldapsOnly` (pour les certificats CA publiquement approuvés), `never` (lors de la connexion via `ldap://` non sécurisé).
`ldapsCACertSecret`	Nom d'un Secret pré-existant contenant le certificat CA du serveur LDAP au format PEM. Doit être créé dans le namespace de l'instance avant d'exécuter `bobctl configure-idp`.
`searchScope`	Détermine la profondeur des recherches dans l'annuaire. `2` recherche tous les conteneurs enfants et sous-arborescences (par défaut) ; `1` limite les recherches aux entrées enfants directes uniquement.
`customUserSearchFilter`	Un filtre supplémentaire appliqué à toutes les opérations de recherche d'utilisateurs, par exemple pour exclure les comptes de service ou restreindre les recherches à des types d'utilisateurs spécifiques.
`userSync.enabled`	Lorsqu'il est défini sur `true`, tous les utilisateurs sont importés lors de la configuration initiale du fournisseur, et les modifications ultérieures de l'annuaire sont synchronisées toutes les cinq minutes. Recommandé pour la plupart des déploiements.
`userAttributeMappings`	Définit le mappage des attributs d'annuaire vers les champs de profil utilisateur Bob, tels que `email`, `firstName` et `lastName`.
`priority`	Détermine l'ordre d'évaluation des fournisseurs lorsque plusieurs fournisseurs sont configurés. Les fournisseurs avec des valeurs inférieures sont vérifiés en premier. La valeur par défaut est `0`.
`groupMapper`	Synchronise les groupes LDAP dans Keycloak. Voir Configuration de la synchronisation des groupes LDAP.

Comportement de synchronisation des utilisateurs

Lorsque userSync.enabled est défini sur true, Bob effectue une importation unique de tous les utilisateurs lors de l'enregistrement du fournisseur LDAP. Une fois l'importation initiale terminée, la synchronisation continue du cycle de vie des utilisateurs est gérée automatiquement via SCIM.

Astuce :

Pour les annuaires LDAP volumineux, envisagez de laisser userSync.enabled défini sur false et de laisser les utilisateurs être provisionnés lors de leur première connexion. Cette approche peut réduire le temps nécessaire pour enregistrer le fournisseur LDAP.

Configuration de la synchronisation des groupes LDAP

Utilise la configuration facultative groupMapper pour synchroniser les groupes LDAP avec Keycloak. Avec la synchronisation des groupes, les utilisateurs et les appartenances aux groupes de ton annuaire LDAP sont importés et gérés via Keycloak.

Le paramètre groupsDn est obligatoire. Tous les autres paramètres sont facultatifs et peuvent être personnalisés pour correspondre au schéma de votre annuaire LDAP et à la structure de vos groupes.

Restriction :

Les groupes bob-admins et bob-users sont des groupes gérés par la plateforme. Ils ne sont pas inclus dans la synchronisation des groupes LDAP.

Paramètre	Valeur par défaut	Description
`groupsDn`	Obligatoire	Distinguished name (DN) de base contenant les entrées de groupes LDAP.
`name`	`groups`	Nom d'affichage du mapper de groupes dans Keycloak.
`groupNameLdapAttribute`	`cn`	Attribut LDAP que Keycloak utilise comme nom de groupe.
`groupObjectClasses`	`groupOfNames`	ObjectClass LDAP identifiant les entrées de groupe.
`membershipLdapAttribute`	`member`	Attribut dans l'entrée de groupe contenant les informations des membres.
`membershipAttributeType`	`DN`	Format des valeurs des membres. Valeurs prises en charge : `DN` (distinguished names) et `UID` (identifiants utilisateur).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Méthode utilisée pour déterminer les appartenances aux groupes.
`memberOfLdapAttribute`	`memberOf`	Attribut utilisateur contenant les informations d'appartenance aux groupes lorsque `GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE` est utilisé.
`customGroupSearchFilter`	Aucune	Filtre LDAP supplémentaire utilisé lors de la recherche de groupes. Le filtre doit être entre parenthèses, par exemple `(cn=dept-*)`.
`mode`	`LDAP_ONLY`	Mode de synchronisation. Valeurs prises en charge : `LDAP_ONLY` et `READ_ONLY`.
`groupsPath`	`/`	Emplacement dans la hiérarchie des groupes Keycloak où les groupes synchronisés sont créés.

Stratégies de récupération de l'appartenance aux groupes

Le paramètre userRolesRetrieveStrategy contrôle la manière dont Keycloak identifie les appartenances aux groupes d'un utilisateur.

Stratégie	Description
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	Récupère les appartenances aux groupes en recherchant les entrées de groupe qui contiennent des références aux utilisateurs.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	Récupère les appartenances aux groupes à partir de l'attribut `memberOf` de l'utilisateur.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	Récupère les appartenances aux groupes de manière récursive, y compris les groupes imbriqués lorsque l'annuaire LDAP le prend en charge.

Astuce :

Utilisez LOAD_GROUPS_BY_MEMBER_ATTRIBUTE à moins que votre annuaire LDAP ne stocke les informations d'appartenance aux groupes dans les entrées d'utilisateurs via l'attribut memberOf ou n'utilise des structures de groupes imbriqués nécessitant des recherches récursives.

Exemple de configuration

# Domaines de messagerie que Bob doit accepter lors de la connexion
domains:
  - corp.example.com

# Utilisateurs auxquels accorder l'accès administrateur Bob
adminEmails:
  - alice@corp.example.com

# Fournisseurs de fédération LDAP
ldaps:
  - name: corp-ldap

    vendor: other
    connectionUrl: ldaps://ldap.corp.example.com:636
    usersDn: ou=People,dc=corp,dc=example,dc=com
    usernameLDAPAttribute: uid
    rdnLDAPAttribute: uid
    uuidLDAPAttribute: entryUUID
    userObjectClasses: inetOrgPerson,organizationalPerson,person

    bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com
    bindPasswordSecret: corp-ldap-bind

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    userSync:
      enabled: true

    userAttributeMappings:
      - ldapAttribute: mail
        userModelAttribute: email
      - ldapAttribute: givenName
        userModelAttribute: firstName
      - ldapAttribute: sn
        userModelAttribute: lastName

    # Optionnel : synchroniser les groupes LDAP dans Keycloak
    groupMapper:
      groupsDn: ou=Groups,dc=corp,dc=example,dc=com
      groupObjectClasses: groupOfNames
      membershipLdapAttribute: member

./bobctl configure-idp --config my-idp.yaml

Valider une configuration IDP avant de l'appliquer

Avant d'appliquer une configuration IDP au cluster, utilise l'option --dry-run pour valider la configuration et prévisualiser les ressources qui seraient créées. L'exécution d'un dry run peut aider à identifier les erreurs de configuration courantes avant que des modifications ne soient apportées au cluster.

./bobctl configure-idp --config my-idp.yaml --dry-run

Le dry run effectue les vérifications suivantes :

Valide que tous les paramètres de configuration obligatoires sont présents dans le fichier de configuration.

Affiche un aperçu de la ressource personnalisée BobIDP qui serait créée ou mise à jour.

Se termine sans créer, modifier ni supprimer aucune ressource dans le cluster.

Remarque :

L'opération de dry run ne valide pas la connectivité réseau au serveur LDAP, n'authentifie pas les identifiants fournis auprès de l'annuaire et ne confirme pas l'existence des Secrets référencés dans le cluster. Ces validations ne sont effectuées qu'après l'application de la configuration et se reflètent dans les conditions d'état LDAPReachable et LDAPAuthenticated.

Appliquer la configuration

Après avoir créé et validé ton fichier de configuration IDP, exécute la commande configure-idp pour appliquer la configuration au cluster.

./bobctl configure-idp --config my-idp.yaml

Option	Obligatoire	Description
`--config <file>`	Oui	Spécifie le chemin vers le fichier de configuration IDP.
`--dry-run`	Non	Valide la configuration et affiche un aperçu des ressources qui seraient créées ou mises à jour, sans appliquer de modifications au cluster.

Lorsque la commande s'exécute, bobctl attend que l'opérateur réconcilie la configuration et valide l'IDP en vérifiant les conditions d'état signalées par la ressource personnalisée BobIDP.

Vérification	Ce qu'elle confirme
`Ready`	La configuration a été appliquée avec succès.
`LDAPRegistered`	Le fournisseur LDAP a été enregistré dans Keycloak.
`LDAPReachable`	Le serveur LDAP est accessible depuis le cluster.
`LDAPAuthenticated`	Les identifiants de liaison configurés sont valides.
`LDAPUserSyncSucceeded`	L'importation initiale des utilisateurs s'est terminée avec succès. Cette condition n'est évaluée que lorsque `userSync.enabled` est défini sur `true`.

Le timeout de validation par défaut est de 600 secondes (10 minutes). Dans les environnements avec de grands annuaires, la synchronisation initiale des utilisateurs peut prendre plusieurs minutes. Pour augmenter le délai d'attente, définis la variable d'environnement BOB_IDP_WAIT_TIMEOUT :

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

Configurer plusieurs fournisseurs LDAP

Pour intégrer des utilisateurs provenant de plusieurs sources LDAP ou Active Directory, ajoute chaque annuaire comme une entrée distincte dans la liste ldaps du fichier de configuration IDP et relance configure-idp.

./bobctl configure-idp --config my-idp.yaml

Inspecter l'état des ressources IDP

Pour afficher l'état de la configuration IDP :

oc get bobidp -n <instance-namespace>

Pour afficher des informations détaillées de configuration et d'état :

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Vérifier l'intégration

Une fois que bobctl configure-idp s'est terminé avec succès, vérifie que l'intégration LDAP fonctionne correctement.

Vérifie l'état de la ressource personnalisée BobIDP :

oc get bobidp bob-idp -n <instance-namespace> -o yaml

Vérifiez que les conditions d'état suivantes sont définies sur True :

Condition	Rôle
`Ready`	Confirme que la configuration a été appliquée avec succès.
`LDAPRegistered`	Confirme que le fournisseur LDAP a été enregistré dans Keycloak.
`LDAPReachable`	Confirme que le cluster peut communiquer avec le serveur LDAP.
`LDAPAuthenticated`	Confirme que les identifiants de liaison configurés sont valides.
`LDAPUserSyncSucceeded`	Confirme que tous les utilisateurs ont été importés avec succès. Présent uniquement lorsque `userSync.enabled: true`.

Si l'une des conditions est False, consultez le champ message correspondant pour obtenir des détails de diagnostic.

Connectez-vous à l'aide des identifiants de l'annuaire LDAP fédéré pour vérifier que l'authentification des utilisateurs fonctionne.

Ouvrez l'URL de Bob :

https://bob.<namespace>.<ingress-domain>

Une connexion réussie confirme que la connectivité, l'authentification, le routage de domaine, le provisionnement SCIM et le mappage des rôles fonctionnent correctement.

Après la première connexion de l'utilisateur, confirmez que la fiche utilisateur est disponible dans Bob.

Ouvrez l'interface d'administration de Bob :

https://bob.<namespace>.<ingress-domain>/admin

Connectez-vous en tant qu'administrateur Bob et vérifiez que l'utilisateur de test apparaît dans la liste des utilisateurs.

Si groupMapper est configuré pour mapper un groupe LDAP aux administrateurs Bob :

Connectez-vous avec un compte utilisateur appartenant au groupe d'administrateurs mappé.
Confirmez que l'utilisateur peut accéder à l'interface d'administration de Bob.
Vérifiez que les fonctions de niveau administrateur sont disponibles.

Si userSync.enabled: true, les utilisateurs sont importés automatiquement après l'enregistrement du fournisseur LDAP. L'utilisateur de test doit apparaître dans Bob sans nécessiter de première connexion.

Si l'utilisateur n'apparaît pas après plusieurs minutes, examinez les journaux de bob-admin pour vérifier s'il y a des erreurs de provisionnement :

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

Examinez toute erreur signalée liée à SCIM et résolvez-la avant de relancer le processus de synchronisation.

Intégration LDAP