We know from the previous posts that Keycloak as an identity provider gives us a platform for managing user identities, securing applications, and integrating with different providers. Therefore, one powerful feature of Keycloak is its ability to integrate with Lightweight Directory Access Protocol (LDAP) directories. This article provides a quick guide for account export to federated realms through migrating users with their credentials and importing groups by custom mappers.

 

Understanding directory services

A directory service is built to manage and store data in a format of key-value pairs. This structure is optimized for read-heavy operations, making it particularly well-suited for information that is frequently accessed but infrequently updated. The data within such a directory is often descriptive, serving to detail various attributes of entities.

For example, imagine using a directory service to manage an address book. Each entry in this address book represents an individual person, with key-value pairs capturing their contact details, place of employment, and other relevant information. This method of data organization is especially beneficial when dealing with qualitative and descriptive information that needs to be easily retrievable.

LDAP operates using a hierarchical directory structure, which enables it to store and access data efficiently. This protocol is widely used to keep track of organizational details, including information about users, assets, and various entities. Its hierarchical model supports a flexible approach to defining and managing these entities and their attributes, ensuring that the directory service remains adaptable to different organizational needs and scalable as data grows.

Key features of LDAP

• Standardized Protocol: LDAP is a widely recognized protocol supported by numerous directory services, including Microsoft Active Directory, OpenLDAP, and Apache Directory Server.
• Hierarchical Structure: LDAP directories are structured hierarchically, similar to a tree, facilitating the efficient organization and retrieval of information.
• Scalability: LDAP is optimized to manage a high volume of read and search operations efficiently, making it ideal for large-scale enterprise environments with extensive user bases.

 

LDAP architecture

Understanding the architecture of LDAP is crucial for maximizing its utility. The primary components include:

 

Directory Information Tree (DIT)

The directory’s hierarchical structure consists of entries, each representing an object like a user, group, or device, and uniquely identified by a Distinguished Name (DN). The DIT is organized hierarchically, with the root of the tree at the top. Below the root are various levels of nodes, each representing different types of entities such as organizations, departments, and individual users. This hierarchical setup allows for an efficient and logical way of managing and accessing directory data.

Attributes / Entries

Attributes are grouped within entities called objectClasses, which are collections of related attributes useful for describing specific entities. When creating an entry, you can utilize the attributes defined by an objectClass by assigning the desired objectClass to the entry. In fact, the objectClass attribute is the only attribute you can set without specifying further objectClasses.

For instance, when creating an entry to represent a person, including the objectClass—or any derived objectClasses—enables the use of all the attributes associated with that specific objectClass. In such an entry, you might set attributes like cn for the common name, description for a brief overview of the entry, and sn for the surname.

Schema

Attribute and object classes are grouped together as something we call a schema. This mechanism takes care of consistency and integrity in the directory tree we use. Unlike relational databases, these schemas are simply collections of related objects and attributes. A single Directory Information Tree (DIT) can utilize multiple schemas to create the necessary entries and attributes.

Schemas typically include extra attribute specifications and may require attributes outlined in other schemas. For instance, the person objectClass requires the inclusion of the surname (sn) attribute for any related entries. In cases where these attributes are absent from the LDAP server, a schema including these definitions can be integrated into the server’s tree structure.

 

Protocol variations

LDAP is essentially a protocol that defines a communication interface for working with directory services, often referred to as LDAP or ldap. There are several variants of the LDAP protocol format worth noting:

• ldaps://: This variation stands for LDAP secured by SSL/TLS. Although standard LDAP traffic is unencrypted, most LDAP implementations support encryption. However, using SSL/TLS for LDAP encryption is deprecated, and the recommended way to secure LDAP connections is STARTTLS.
• ldap://: This is a standard LDAP protocol that provides structured access to a directory service.
• ldapi://: This variation stands for LDAP over IPC (Inter-Process Communication). Typically used for secure local connections to an LDAP system for administrative purposes, for example using internal sockets.

While all three formats use the LDAP protocol, the two of them provide just additional context on the method of communication.

 

Returning to the realm and configuring LDAP

After familiarizing yourself with the theory of LDAP operation, we can return to the realm, whose configuration we mentioned in the previous post (you can find it here), and go to the User Federation tab, where we can enter the necessary data to connect to the LDAP server provided by the sample provider.

The essential information we need includes the connection URL, the distinguished name of the LDAP admin (bind DN), and the distinguished name of the users (users DN), which is the parent of all users in the LDAP tree. Most attributes, such as the LDAP username, LDAP UUID, or user object classes, can be left at their default values as they align with our LDAP server provider requirements.

After synchronizing users, we see that two new entries have appeared in the Users tab. Synchronization with LDAP offers more possibilities than just simple user account import. Let’s check out how mappers work.

Example 1: hardcoded-attribute-mapper

For instance, we can mark imported users by assigning them a custom attribute. This can be done using a hardcoded-attribute-mapper, which assigns a new attribute, authenticationMethod, to each new user and gives it the value “ldap”. 

In the Users -> User Details -> Attributes tab, we can then see that users originating from LDAP indeed have this attribute. It can, for example, be included in access tokens.

Example 2: group-ldap-mapper

Often, LDAP defines a system of roles or groups that imported users belong to. Keycloak can also import groups and automatically assign the aforementioned users to them. To do this, we can configure another mapper, this time of the group-ldap-mapper type, as shown in the image below:

In this case, the distinguished name for groups will be the same as the DN for all users, i.e.

ou=Users,o=66a20b93d2f2fc6db2e89ff3,dc=jumpcloud,dc=com

The groups stored in LDAP are defined by an object class named groupOfNames, which means that the attribute representing membership on the LDAP side will typically be member. Now, let’s try synchronizing our groups.

As we can see, three groups were correctly imported, along with the relationships between a group and its users. Therefore, LDAP administrators can easily receive the corresponding permissions on our realm side. Subsequently, we could link specific roles to a given group to manage resource access even more conveniently.

Summary

Integrating Keycloak with LDAP is a powerful tool for managing identities and security within an organization. This integration allows for efficient synchronization of users and groups from LDAP, enabling centralized management of permissions and resource access. Key steps include configuring the LDAP connection, synchronizing data, and using mappers to customize imported information, such as attributes and user groups. It’s important to understand LDAP’s architecture and operations to fully leverage its capabilities. Implementing LDAP with Keycloak not only streamlines account management but also enhances security and simplifies integration with existing systems. By utilizing mappers, we can further tailor how information is imported and used in our system, leading to better organization and control over access within the organization.