LDAP integration with Keycloak

par | Oct 5, 2020 | Gestion des Identités, LDAP, SSO

LDAP integration with Keycloak seems to be confusing for a lot of us, and we face a lot of questions about it, it’s why we try in this article to become clearer in this article.

Active Directory or LDAP ?

LDAP (Lightweight Directory Access Protocol) is a protocol for directory service providers. Active Directory is a directory service provider. LDAP is the « API », Active Directory the « backend » with the database.

Microsoft reveal Active Directory in 1996, first wide deployment was in 1999 with Windows 2000 server

LDAP was created in 1992, that’s why this protocol is mostly used on multi-users systems.

Requirements

For this examples, we have :

  • A running LDAP server with a directory behind. In our case, we use a Synology LDAP Server. All examples can run with any LDAP server, depending on your system. Of course, Windows Server Active Directory works perfectly
  • A Keycloak realm. Feel free to subscribe to Please Open It Keycloak As A Service. All examples were made with a free realm.
  • LDAP Admin, a free software for LDAP directory management. We will use only this interface.

LDAP structure

LDAP Admin can show all details on any node of your directory. Very useful to use it when you need to integrate LDAP in other systems with complete references.

Our directory has a standard structure :

  • Roles (as Organization Unit) with groups
  • Groups (as Common Name, as Synology created it) with groups
  • List of users

Keycloak user federation VS identity provider

There are 2 entries in Keycloak : User federation and identity provider. Those two approaches are significantly different, by the method and the result. The result is not how users are provided.

Identity provider

By « identity provider », it means an identity server. Authentication process is delegated to the identity provider. Only if the user exists, is correctly authenticated and gives the right permissions the identity provider will return the identity. Check our blogpost about Authorization code.

User federation
Understanding keycloak user Federation

« The way we store users » could be a good way to explain it. We can replace the user’s management delivered by default in Keycloak by another method. It works with LDAP or Keberos by default, there are also some developer interfaces (SPI) if you want to code your own user management.

Add LDAP to Keycloak

First of all, we have to get the user structure and properties. With LDAP Admin it is easy :

Then we have enough informations to fill the LDAP configuration in Keycloak.

  • Username attribute is uid
  • Two classes for user object : inetOrgPerson and organizationalPerson
  • Users DN is cn=users,dc=please-open,dc=it
  • Admin user is : uid=root,cn=users,dc=please-open,dc=it

Our advice is : do not rely on default values provided by « vendor » values. Check the right values using a LDAP explorer software.

Save the configuration, then you can synchronize all users for the first time.

Our users are now in the database, let’s take a look :

Users details are filled by the default import. Note the « Verify email » action required.

In the LDAP configuration we do not check « trust email » in « Advanced section »

More attributes are also provided by default mappers :

Those mappers are defined in the « mappers » section :

Credentials are provided directly by the LDAP, so the entry shows this :

GREAT ! The user’s synchronization works perfectly as we want. We define a synchronization period :

Group Mapping

In LDAP, we can organize users by groups (with a property « memberOf »). This concept of « groups » does not exist in oauth2/openid Connect. There is only role mapping (realm roles or client roles) with users.

Keycloak has its own group implementation. This implementation is only a role mapping shortcut, each member of a group will have the role.

Check the groups structure in the LDAP Admin :

  • LDAP Group DN is cn=groups,dc=please-open,dc=it
  • Group object class is apple-group
  • membership LDAP attribute is member
  • User attribute is still uid

Now, add a new LDAP Mapper, with the type « group-ldap-mapper », then we have to fill a big form like seen previously :

Then, we sync all.

The Keycloak group structure is now the same that is defined in our directory :

Of course, we have correctly filled the users attributes so the users are affected to their groups.

Role mapping

We have an Organizational Unit for roles. It is also the same as groups. In Keycloak, we will define the mapping directly to roles.

Check all attributes names :

  • class is posixGroup
  • name is cn
  • Members defined in memberUid, directly with uid

Define a new LDAP Mapper, using the mapper type « role-ldap-mapper ». Fill all fields with values we got previously :

2 ways exist for roles : realm role (global) or client based roles.

We chose the « backend » client for our use. The mapping will create roles in the client.

Users will have the roles assigned after synchronization :

Keeping the same structure between LDAP and openid connect is great for already running projects. As consultants, we see many companies that rely on their directory structure, the only source of truth.

Keycloak can use the directory in read only mode or with a bi-directionnal synchronization. Do not forget to consider it.

Mathieu PASSENAUD
Les derniers articles par Mathieu PASSENAUD (tout voir)