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

Bob on-premises intègre votre environnement LDAP ou Active Directory à Keycloak via l'utilitaire bobctl, qui configure l'annuaire en tant que fournisseur de fédération d'utilisateurs Keycloak. Bien que cette intégration soit généralement configurée lors de l'installation, elle peut également être configurée, mise à jour ou gérée après le déploiement dans le cadre des activités courantes de gestion des utilisateurs.

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éez un fichier de configuration LDAP à partir du modèle fourni avant d'enregistrer un fournisseur LDAP.

cp config-ldap-template.yaml my-ldap.yaml

Le fichier de configuration contient des paramètres obligatoires et facultatifs qui définissent comment Bob se connecte, s'authentifie et synchronise les utilisateurs depuis votre annuaire LDAP.

Champs obligatoires

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.
`domains`	Un ou plusieurs domaines de messagerie associés à l'annuaire. Lors de l'authentification, les utilisateurs dont l'adresse e-mail correspond à l'un des domaines configurés sont automatiquement dirigés vers ce fournisseur LDAP pour la validation des identifiants.

Important :

Le paramètre domains est la seule méthode prise en charge pour configurer le routage par domaine dans les déploiements on-premises. Ne configurez pas les domaines via l'interface utilisateur d'administration de Bob car cela n'est pas pris en charge et peut entraîner des erreurs d'authentification.

Champs facultatifs

Champ	Description
`adminEmails`	Adresses e-mail des utilisateurs auxquels accorder des privilèges d'administrateur. Bob attribue automatiquement l'accès administrateur à ces utilisateurs.
`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`	Fait référence au Secret stockant le mot de passe du compte de liaison. Ce Secret est automatiquement créé lorsque l'option `--bind-password` est fournie avec la commande `bobctl`.
`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`	Fait référence au Secret contenant le certificat CA du serveur LDAP au format PEM. Ce Secret est automatiquement créé lorsque `--ca-cert-file` est fourni.
`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

Utilisez la configuration facultative groupMapper pour synchroniser les groupes LDAP avec Keycloak. La synchronisation des groupes permet d'importer et de gérer via Keycloak les utilisateurs et les appartenances aux groupes définis dans votre annuaire LDAP.

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 et sont automatiquement exclus de 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

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

domains:
  - corp.example.com

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

useTruststoreSpi: always

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 add-ldap --config corp-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Valider une configuration LDAP avant de l'appliquer

Avant d'appliquer une configuration LDAP au cluster, utilisez 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 add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt \
  --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.

Vérifie que le fichier de certificat CA spécifié est disponible localement lorsque --ca-cert-file est utilisé.

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

Affiche les Secrets Kubernetes qui seraient générés dans le cadre de la configuration.

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é votre fichier de configuration LDAP, exécutez la commande add-ldap pour appliquer la configuration au cluster.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

Option	Obligatoire	Description
`--config <file>`	Oui	Spécifie le chemin vers le fichier de configuration LDAP.
`--bind-password <password>`	Non	Crée le `bindPasswordSecret` dans le cluster. Non requis lorsque l'annuaire autorise les liaisons anonymes.
`--ca-cert-file <path>`	Non	Crée le `ldapsCACertSecret` à partir d'un fichier PEM local. Peut être omis lors de l'utilisation d'une CA publiquement approuvée ou d'une connexion `ldap://` non sécurisée.
`--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 le fournisseur LDAP en vérifiant les conditions d'état signalées par la ressource personnalisée BobLDAP.

Vérification	Ce qu'elle confirme
`Ready`	Le fournisseur a été créé et enregistré avec succès.
`LDAPReachable`	Le serveur LDAP est accessible depuis le cluster.
`LDAPAuthenticated`	Les identifiants de liaison configurés sont valides.
`UserSyncSucceeded`	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éfinissez la variable d'environnement BOB_LDAP_WAIT_TIMEOUT :

BOB_LDAP_WAIT_TIMEOUT=900 ./bobctl add-ldap --config my-ldap.yaml

Configurer plusieurs fournisseurs LDAP

Pour intégrer des utilisateurs provenant de plusieurs sources LDAP ou Active Directory, créez un fichier de configuration distinct pour chaque annuaire et attribuez une valeur unique au champ name dans chaque configuration.

./bobctl add-ldap --config ldap-corp.yaml
./bobctl add-ldap --config ldap-subsidiary.yaml

Inspecter l'état des ressources LDAP

Pour afficher l'état des fournisseurs LDAP configurés :

oc get bobldap -n <instance-namespace>

Pour afficher des informations détaillées de configuration et d'état pour un fournisseur spécifique :

oc get bobldap <name> -n <instance-namespace> -o yaml

Vérifier l'intégration

Une fois que bobctl add-ldap s'est terminé avec succès, vérifiez que l'intégration LDAP fonctionne correctement.

Vérifiez l'état de la ressource personnalisée BobLDAP :

oc get bobldap <name> -n <instance-namespace> -o yaml

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

Condition	Rôle
`Ready`	Confirme que le fournisseur LDAP a été enregistré avec succès.
`LDAPReachable`	Confirme que le cluster peut communiquer avec le serveur LDAP.
`LDAPAuthenticated`	Confirme que les identifiants de liaison configurés sont valides.
`UserSyncSucceeded`	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