Fédérer un annuaire LDAP ou AD avec Keycloak

Cette page connecte Keycloak à un annuaire LDAP ou Active Directory existant. Vos comptes restent dans l'annuaire, référence unique de l'entreprise ; Keycloak les fédère pour les exposer à vos applications en OIDC ou SAML, sans jamais recopier les mots de passe. Le guide couvre la création du provider de fédération, la synchronisation des utilisateurs, l'authentification déléguée et les mappers d'attributs. Public : administrateur qui a déjà un annuaire (OpenLDAP, Active Directory, FreeIPA) et un realm Keycloak.

Les notions de DN, OU, bind et schéma LDAP ne sont pas détaillées ici ; elles sont expliquées dans LDAP, Active Directory et Kerberos. Cette page se concentre sur la configuration Keycloak.

Ce que vous allez apprendre

• Distinguer fédération et import manuel, et savoir où vivent utilisateurs et mots de passe
• Créer un provider de fédération LDAP dans un realm, en console et en ligne de commande
• Synchroniser les utilisateurs de l'annuaire vers Keycloak
• Vérifier que l'authentification est bien déléguée à l'annuaire
• Adapter la configuration aux spécificités d'Active Directory

Prérequis

Avant de commencer, il vous faut :

• Une instance Keycloak fonctionnelle avec un realm applicatif. Voir Installer Keycloak et Administrer Keycloak.
• Un annuaire LDAP accessible depuis Keycloak, avec un compte de service pour le bind. Les exemples utilisent un OpenLDAP servant la base dc=exemple,dc=fr et l'unité d'organisation ou=people. Pour un annuaire léger de test, voir Monter un LDAP avec LLDAP.
• L'URL de connexion, le bind DN (compte de lecture) et le DN des utilisateurs de votre annuaire.

Comprendre la fédération

La fédération ne copie pas votre annuaire dans Keycloak : elle le branche dessus. À chaque connexion, Keycloak interroge l'annuaire pour vérifier l'identité et le mot de passe. L'annuaire reste la source de vérité, Keycloak n'est qu'une façade qui parle OIDC et SAML aux applications.

C'est le point qui déroute au début : par défaut, le mot de passe ne quitte jamais l'annuaire. Keycloak le transmet à l'annuaire pour vérification (bind), mais ne le stocke pas. Un utilisateur importé apparaît dans la liste du realm, mais son mot de passe n'y est pas.

Le comportement se règle avec le mode d'édition (editMode), qui décide qui peut modifier quoi :

Mode d'édition	Modifications dans Keycloak	Écrites vers l'annuaire	Cas d'usage
READ_ONLY	Interdites	Non	L'annuaire est géré ailleurs (le plus courant)
WRITABLE	Autorisées	Oui	Keycloak est l'outil d'administration de l'annuaire
UNSYNCED	Autorisées	Non (copie locale)	Surcharge locale sans toucher à l'annuaire

Glissez pour voir

Commencez toujours en READ_ONLY. C'est le mode le plus sûr : Keycloak ne peut rien casser dans l'annuaire de production. Vous passerez à WRITABLE seulement si Keycloak devient l'outil de gestion de cet annuaire.

Étape 1 - Repérer la structure de l'annuaire

Avant de configurer Keycloak, identifiez où sont les utilisateurs et sous quels attributs. Une recherche LDAP le confirme :

ldapsearch -x -H ldap://ldap.exemple.fr \
  -b "ou=people,dc=exemple,dc=fr" \
  -D "cn=admin,dc=exemple,dc=fr" -w 'MotDePasseBind' \
  "(objectClass=inetOrgPerson)" uid cn mail

dn: uid=bob,ou=people,dc=exemple,dc=fr
uid: bob
cn: Bob Durand
mail: bob@exemple.fr

dn: uid=carol,ou=people,dc=exemple,dc=fr
uid: carol
cn: Carol Nguyen
mail: carol@exemple.fr

Notez les trois informations dont Keycloak a besoin :

• DN des utilisateurs (usersDn) : ou=people,dc=exemple,dc=fr
• Attribut d'identifiant : uid sur OpenLDAP, sAMAccountName sur Active Directory
• Classe d'objet : inetOrgPerson sur OpenLDAP, user sur Active Directory

Étape 2 - Créer le provider de fédération

Console web

1. Dans votre realm, ouvrez User federation > Add LDAP providers.

2. General options :

   • UI display name : openldap-exemple
   • Vendor : Other (ou Active Directory pour un AD)

3. Connection and authentication :

   • Connection URL : ldaps://ldap.exemple.fr:636 (LDAPS recommandé)
   • Bind type : simple
   • Bind DN : cn=admin,dc=exemple,dc=fr
   • Bind credentials : le mot de passe du compte de service

4. LDAP searching and updating :

   • Edit mode : READ_ONLY
   • Users DN : ou=people,dc=exemple,dc=fr
   • Username LDAP attribute : uid
   • RDN LDAP attribute : uid
   • UUID LDAP attribute : entryUUID
   • User object classes : inetOrgPerson

5. Test connection puis Test authentication, et Save.

Ligne de commande

En ligne de commande, le provider est un composant du realm. On décrit sa configuration dans un fichier JSON, ce qui rend la fédération reproductible d'un environnement à l'autre :

{
  "name": "openldap-exemple",
  "providerId": "ldap",
  "providerType": "org.keycloak.storage.UserStorageProvider",
  "parentId": "REALM_ID",
  "config": {
    "enabled": ["true"],
    "vendor": ["other"],
    "connectionUrl": ["ldaps://ldap.exemple.fr:636"],
    "bindDn": ["cn=admin,dc=exemple,dc=fr"],
    "bindCredential": ["MotDePasseBind"],
    "usersDn": ["ou=people,dc=exemple,dc=fr"],
    "usernameLDAPAttribute": ["uid"],
    "rdnLDAPAttribute": ["uid"],
    "uuidLDAPAttribute": ["entryUUID"],
    "userObjectClasses": ["inetOrgPerson"],
    "editMode": ["READ_ONLY"],
    "importEnabled": ["true"],
    "searchScope": ["1"]
  }
}

REALM_ID est l'identifiant interne du realm, récupéré ainsi :

kcadm.sh get realms/lab --fields id --format csv --noquotes

On crée ensuite le provider à partir du fichier :

kcadm.sh create components -r lab -f ldap-provider.json

entryUUID, l'ancre stable de l'identité

L'UUID LDAP est l'attribut que Keycloak utilise pour reconnaître un utilisateur d'une synchro à l'autre, même s'il est renommé. Sur OpenLDAP c'est entryUUID, sur Active Directory c'est objectGUID. Ne le calez jamais sur uid ou cn : ces attributs changent, et Keycloak créerait alors des doublons à chaque renommage.

Étape 3 - Synchroniser les utilisateurs

Deux mécanismes peuplent le realm. La synchronisation à la demande importe un utilisateur la première fois qu'il se connecte : discret, mais l'utilisateur n'existe dans Keycloak qu'après sa première connexion. La synchronisation complète importe tout l'annuaire d'un coup, utile pour peupler le realm immédiatement et attribuer des rôles avant la première connexion.

Depuis la console, le bouton Sync all users déclenche une synchro complète. En ligne de commande :

compid=$(kcadm.sh get components -r lab -q name=openldap-exemple \
  --fields id --format csv --noquotes)

kcadm.sh create "user-storage/$compid/sync?action=triggerFullSync" -r lab

La liste des utilisateurs du realm confirme l'import. Les comptes venus de l'annuaire portent un lien de fédération, contrairement aux comptes créés localement :

kcadm.sh get users -r lab --fields username,email,federationLink

alice | alice@exemple.fr | federe: False
bob   | bob@exemple.fr   | federe: True
carol | carol@exemple.fr | federe: True

bob et carol viennent de l'annuaire, alice a été créée dans Keycloak. Pour maintenir le realm à jour sans intervention, activez la synchronisation périodique dans le provider (par exemple toutes les heures) : les nouveaux comptes de l'annuaire apparaîtront automatiquement.

Étape 4 - Vérifier l'authentification déléguée

C'est le test qui prouve que la fédération fonctionne : un utilisateur de l'annuaire se connecte avec le mot de passe stocké dans l'annuaire, pas dans Keycloak. On demande un token pour bob avec ses identifiants LDAP :

curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST http://localhost:8080/realms/lab/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=test-cli \
  -d username=bob \
  -d password='MotDePasseBob1!' \
  -d scope=openid

200

Le code 200 et le token retourné confirment la délégation : Keycloak a transmis le mot de passe à l'annuaire pour vérification (bind), l'annuaire a répondu favorablement, Keycloak a émis le token. À aucun moment le mot de passe de bob n'a été stocké dans Keycloak.

Le flow password ici, c'est pour le test

L'appel ci-dessus utilise le flow password uniquement pour valider la fédération en ligne de commande. Vos vraies applications, elles, utilisent Authorization Code + PKCE. L'utilisateur fédéré verra alors la page de login Keycloak et saisira son mot de passe d'annuaire, sans que l'application ne le manipule jamais.

Étape 5 - Mapper les attributs et les groupes

Keycloak crée automatiquement des mappers qui relient les attributs LDAP aux champs utilisateur : uid vers le nom d'utilisateur, mail vers l'email, cn/sn vers le nom complet. Ils apparaissent dans l'onglet Mappers du provider et couvrent la plupart des besoins sans réglage.

Le mapper à ajouter manuellement, dans presque tous les cas, est le group-ldap-mapper : il fait remonter les groupes de l'annuaire (souvent ou=groups) comme groupes Keycloak. Vos applications reçoivent alors les appartenances de groupe dans le token, ce qui permet d'attribuer des droits sans gérer les groupes deux fois. Configurez-y le DN des groupes, la classe d'objet (groupOfNames sur OpenLDAP, group sur AD) et l'attribut de membre (member).

Active Directory : ce qui change

Active Directory est un annuaire LDAP, mais avec ses propres attributs. Sélectionnez Vendor : Active Directory dans le provider, ce qui pré-remplit la plupart des champs. Les différences à connaître :

Réglage	OpenLDAP	Active Directory
Username LDAP attribute	uid	sAMAccountName (ou cn)
UUID LDAP attribute	entryUUID	objectGUID
User object classes	inetOrgPerson	person, organizationalPerson, user
Attribut d'email	mail	mail (parfois userPrincipalName)

Glissez pour voir

Sur AD, prévoyez aussi de gérer les comptes désactivés (attribut userAccountControl) pour qu'un compte désactivé côté AD ne puisse plus se connecter via Keycloak. Le mapper msad-user-account-control-mapper, ajouté par défaut quand le vendor est AD, s'en charge.

Sécurité

La fédération relie Keycloak à l'annuaire le plus sensible de l'entreprise. Quelques règles :

• LDAPS ou StartTLS obligatoire en production. Un bind en clair (ldap://) expose le mot de passe du compte de service et ceux des utilisateurs sur le réseau. Utilisez ldaps:// (port 636) et importez le certificat de l'annuaire dans le truststore de Keycloak.
• Compte de bind en lecture seule, limité à l'OU des utilisateurs. N'utilisez jamais un compte administrateur du domaine pour le bind.
• Edit mode READ_ONLY tant que Keycloak n'est pas l'outil de gestion de l'annuaire. Cela évite qu'une action dans Keycloak modifie l'annuaire de production.
• Secret de bind hors du dépôt Git : traité comme un mot de passe, injecté par variable d'environnement ou coffre-fort. Voir HashiCorp Vault.
• Filtre LDAP restrictif (customUserSearchFilter) pour ne fédérer que les comptes concernés, pas tout l'annuaire.

Dépannage

Symptôme	Cause probable	Solution
Test connection échoue	URL, port ou pare-feu	Vérifier que Keycloak joint l'annuaire (ldapsearch depuis le serveur Keycloak)
Test authentication échoue	Bind DN ou mot de passe erroné	Vérifier le compte de service et son DN complet
Synchro : 0 utilisateur importé	usersDn ou userObjectClasses incorrect	Recopier le DN exact et la classe vus dans ldapsearch
Doublons à chaque synchro	UUID mal réglé (uid au lieu de entryUUID)	Corriger l'UUID LDAP attribute puis resynchroniser
Utilisateur AD introuvable	sAMAccountName non configuré	Vendor Active Directory + username attribute sAMAccountName
Erreur de certificat en LDAPS	Certificat de l'annuaire absent du truststore	Importer le certificat CA dans le truststore Keycloak

Glissez pour voir

À retenir

• La fédération branche Keycloak sur l'annuaire ; les utilisateurs et les mots de passe restent dans l'annuaire, qui demeure la source de vérité.
• Le mode d'édition READ_ONLY est le défaut sûr : Keycloak ne peut rien modifier dans l'annuaire de production.
• L'UUID LDAP (entryUUID sur OpenLDAP, objectGUID sur AD) est l'ancre stable qui évite les doublons entre synchros.
• La synchro complète peuple le realm immédiatement ; la synchro à la demande importe à la première connexion.
• Un token obtenu avec le mot de passe d'annuaire prouve l'authentification déléguée : le mot de passe n'est jamais stocké dans Keycloak.
• Active Directory change surtout les attributs (sAMAccountName, objectGUID, classe user) ; le reste de la logique est identique.

Prochaines étapes

LDAP, Active Directory et Kerberos Les concepts d'annuaire d'entreprise : DN, OU, bind, schéma.

Sécuriser une application (OIDC) Connecter vos applications au realm que vous venez de fédérer.

Monter un LDAP avec LLDAP Un annuaire léger et moderne pour tester la fédération.

Administrer Keycloak Realms, utilisateurs, groupes et rôles dans la console.

Stocker les secrets avec Vault Sortir le secret de bind du code et des dépôts Git.

×

📖 Voir la documentation →