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.

 

As organizations expand and incorporate a variety of applications and services, managing user identities across these systems becomes increasingly complex. Keycloak, an open source identity provider, effectively addresses this challenge by offering user federation capabilities. This feature enables the server to connect with existing user stores, facilitating integration and centralized management of user identities. Consequently, organizations can centrally manage user identities without needing to migrate users from their current systems.

 

Understanding User Federation concept

User federation in Keycloak refers to the ability to connect to external user stores, such as LDAP (Lightweight Directory Access Protocol) servers, Active Directory (AD), or custom databases. This connection allows Keycloak to authenticate and manage users from external sources without migrating users with their credentials. Keycloak acts as an intermediary, handling authentication requests and retrieving user information from the external stores as needed. This makes Keycloak LDAP integration and Active Directory Keycloak integration straightforward and effective.

 

Key benefits of using User Federation:

• •  Centralized authentication – users can authenticate across multiple applications using a single set of credentials. It ensures that user data remains consistent across different realms or systems, improving the user experience.This supports centralized identity management.
  • Seamless integration – organizations can integrate existing user stores without migrating users to a new system. It helps with onboarding users into new environments by exporting their accounts directly to the target realm. This is particularly beneficial for Keycloak SSO integration and Keycloak custom database integration.
  • Improved security – centralized user management enhances security by enabling consistent enforcement of security policies. This ensures adherence to Keycloak security policies.
  • Scalability – it supports evolution of organizational infrastructure by enabling smooth transitions and integrations between various identity stores. This helps in Keycloak scalability solutions and managing Keycloak multi-realm setup.

Example Use Case

Consider a multinational corporation that maintains distinct Keycloak realms for different regions, such as Europe and North America. By leveraging the concept of user federation, the company can ensure that user accounts created in the European realm are seamlessly accessible in the North American realm. This allows users to access services across regions without the need to manage multiple sets of credentials, thereby enhancing both user experience and administrative efficiency. This is an example of Keycloak multinational identity management and Keycloak regional user management.

Connecting to external user stores

Keycloak supports various user federation providers, including LDAP and Active Directory. To connect Keycloak to an external user store:

• Log in to the Keycloak admin console and select the appropriate realm.
• Navigate to the User Federation tab and add the relevant provider, such as LDAP or Active Directory.
• Enter the connection details for the external user store, such as the connection URL and bind credentials.

Configuring synchronization settings

By synchronizing with LDAP, Keycloak can leverage existing user credentials, allowing users to authenticate with the same username and password they use across other systems. Sync ensures that user data such as profiles, roles and permissions are consistently maintained between KC and LDAP server.

In import mode, Keycloak periodically synchronizes user data from the LDAP server into its own internal database. This means that user data is copied between the servers. Since data is stored locally, users can be authenticated even if the LDAP server is temporarily unavailable. Also local data access can be faster than querying LDAP for every authentication request. But there is still a potential lag between updates due to periodic synchronization. It is better suited for environments where LDAP server availability might be an issue, where performance is a critical concern, and where there is a need for user data customization within Keycloak. We consider two types of users synchronization:

 – Scheduled full sync at regular intervals to ensure all user data is up-to-date. It’s easier to configure and reduces the risk of missing updates or inconsistencies due to overlooked changes. But can also be resource-intensive and time-consuming, especially with a large user base.

Scheduled full read-only sync with import mode on

 – Incremental sync to update only the users whose data has changed since the last sync. With a large number of users, incremental sync is more efficient as it reduces the amount of data being transferred. It is ideal for environments where minimizing resource usage is important.

If import mode is off, Keycloak acts as a proxy to the LDAP server, querying it directly for user information as needed. And no user data is stored locally. This ensures real-time data accuracy as Keycloak always queries the latest data and it also reduces storage requirements as no data is duplicated in Keycloak. In this scenario users may experience latency due to real-time querying. In general, it strongly depends on the availability of the LDAP server for every authentication request. This solution is preferable when data consistency and accuracy are paramount, and the LDAP server is reliable and capable of handling real-time queries without performance degradation.

Managing attribute mappings

There are fields in LDAP that contain user-specific information such as ‘uid’, ‘cn’, ‘sn’, ‘mail’, etc. In Keycloak, these LDAP attributes are mapped to Keycloak-specific user attributes. LDAP attributes can also define user roles. These roles can be synchronized, allowing users to have the same permissions in both LDAP and Keycloak. 

Attributes can be used to define conditional logic for authentication and authorization policies. For example, access can be granted based on specific attribute values. They can be later dynamically updated based on user interactions or other events, allowing for flexible and adaptive policy enforcement. In most cases we synchronize them in one direction, typically from LDAP to Keycloak. But in some configurations, attributes can be synchronized bidirectionally, allowing changes in Keycloak to be propagated back and vice versa. This requires careful configuration to prevent conflicts.

LDAP mappers are used to define how LDAP attributes are mapped to Keycloak attributes. This can be configured via the LDAP provider settings. If default mappers do not meet requirements, custom mapper can be created to handle specific attribute synchronization needs. Attributes can also be transformed during synchronization. For instance, an LDAP attribute storing a full name might be split into firstName and lastName attributes in Keycloak. In some scenarios, attributes from both environments may need to be merged. Keycloak provides mechanisms to handle such merging strategies.

Summary

User federation significantly enhances Keycloak’s user management functionality. It provides organizations with a powerful tool to manage user identities across multiple environments, ensuring data consistency, simplifying user onboarding, and enhancing overall security. By leveraging Keycloak for user federation and account export to federated realms, organizations can streamline identity management and support scalable, secure, and efficient operations.

 

Do you want to discuss the cybersecurity of your company? Contact us.

[contact-form-7]