Red Hat
Aug 20, 2015
by Marek Posolda

LDAP integration in Keycloak is done through User Federation SPI. It works in a way that users are synced from LDAP into Keycloak database. This is needed because Keycloak needs to store various metadata about users and some of them may not be supported by the LDAP schema. The configuration of LDAP Federation provider in admin console is flexible enough, so you can choose whether your LDAP server is read-only or writable and whether new users created in Keycloak will be synced back to LDAP or just into Keycloak database etc.

Before 1.3.1 release we pulled just basic data of users from LDAP like first name, surname, email, username and password. From 1.3.1 we improved this and added support for LDAP mappers. This allows you even more flexibility in configuring which LDAP data are synced to Keycloak and back (for writable LDAP). Right now we have:

  • User Attribute mapper - This allows to specify which LDAP attributes are mapped to which User attributes in Keycloak. As you can see there are various things you can configure. For example you can specify if attribute is read-only. In this case will be data synced from LDAP to Keycloak DB, but not back to LDAP in case that user is changed in Keycloak.
  • Full name mapper - Allows some additional flexibity in mapping full name. Many LDAP deployments have full name in single LDAP attribute like "cn: John Doe". This mapper will ensure that this single attribute is properly mapped to first name and lastname in Keycloak DB
  • Role mapper - Allows to map role mappings from LDAP into Keycloak. You can specify LDAP DN where are roles configured and you can specify whether the roles are mapped into realm roles in Keycloak or to client roles of specified client. You can also specify the mode like whether role mappings are read-only or writable to LDAP etc.
Mapper SPI provides few callback methods, which are executed at the point when new user is registered in Keycloak, imported from LDAP or searched in Keycloak. You can implement the SPI and add your own mapper if default implementations are not sufficient.

Mappers were added in older 1.3.1 release, but in 1.4 we added more improvements and fixed lot of bugs based on the feedback from community. We also added simple LDAP example, which is part of Keycloak example distribution . It's really easy to have the example up and running, as it contains embedded ApacheDS based LDAP server, so only thing you need is JDK and maven. More documentation about mappers is in Keycloak documentation but note that admin console contains tooltips on various options and hence is quite self-documenting.

It's still possible that you can see the issues - various organizations have various data in their LDAP servers and it's quite a challenge to handle everything correctly in Keycloak. In this case, feel free to write questions on our keycloak-user mailing list or create JIRA.

Original Post