> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/identity-and-access-management-iam/keycloak/user-federation/integrating-openldap.md).

# Integrating OpenLDAP

## Objective

Connect a local OpenLDAP server (running via Docker) to Keycloak, so that users and groups can be read, synced, and authenticated via Keycloak.

## Prerequisites

Make sure the following services are running:

| Service          | Tool                    | Example URL              |
| ---------------- | ----------------------- | ------------------------ |
| **LDAP Server**  | `osixia/openldap` image | `ldap://localhost:389`   |
| **phpLDAPadmin** | Admin GUI               | `https://localhost:6443` |
| **Keycloak**     | Identity provider       | `http://localhost:8180`  |

We should already have:

* A working `docker-compose.yml`
* Seeded users and groups via `seed-data.ldif`
* Admin DN and password (e.g., `cn=admin,dc=corp,dc=acme,dc=com`)

Refer to the following pages for more details on the setup

{% content-ref url="/pages/N9jgDSkFNVz6i60BghmF" %}
[Local OpenLDAP Setup](/the-programmers-guide/identity-and-access-management-iam/ldap/local-openldap-setup.md)
{% endcontent-ref %}

## Apply LDAP Config

### Log into Keycloak Admin Console

1. Open `http://localhost:8180`
2. Log in as the Keycloak admin user (e.g., `admin / admin`)
3. Select the target **Realm** (e.g., `master`, or create a new one say `employee`)

### Add LDAP User Federation Provider

1. Go to **User Federation** (left-hand menu)
2. Click **Add provider → ldap**

### Set Configurations

<figure><img src="/files/GshIUZgz0eSwEdt9wFrI" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/AW42SYKR3jyAw7gxe5YA" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Zu4Ynv1qahIvnB1R9oLr" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/t7HRhShe1JH4ExgT17s7" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/V8j9s2HFSnXZXy7S7FjK" alt=""><figcaption></figcaption></figure>

### Test the Connection

Use the **"Test connection"** and **"Test authentication"** buttons at the bottom of the provider form:

* **Test connection**: Validates LDAP connectivity
* **Test authentication**: Confirms bind credentials work

If any test fails, double-check:

* LDAP port (`389` open?)
* Bind DN/password
* Network access between Keycloak container and LDAP container

## Sync and Verify Users

Click **"Synchronize all users"** from the LDAP provider settings. This will import all matching users under `Users DN` into Keycloak.

<figure><img src="/files/nD7rXhMf0TmpQHhiBK8m" alt=""><figcaption></figcaption></figure>

Sample users available in LDAP (Seeds file)

<figure><img src="/files/RgcskbSXRCqUf1tmT9Hy" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/uOtGt0rQFW7DlwH5Em9q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/wL8KHkKOlv3eGObzY8kC" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/FDPXxHkK8JcEhqplwCAK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/djoZlmpG3J9cggWLYq4j" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/e4tFVUa2YDns1t13vSDw" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/5Jt0s5GNfFSXYgi1Iis0" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/o5biM6tP3LcILw7LUL1i" alt=""><figcaption></figcaption></figure>

Fetch Token

<figure><img src="/files/XrbV8iYiqHk83Xi6lSN6" alt="" width="563"><figcaption></figcaption></figure>

## Configure LDAP Mappers

By default, Keycloak adds a few LDAP mappers. We can verify and adjust them

| **Mapper Type** | Example Mapping |
| --------------- | --------------- |
| Username        | `uid`           |
| Email           | `mail`          |
| First Name      | `givenName`     |
| Last Name       | `sn`            |
| Full Name       | `cn`            |

> We can also add custom mappers for attributes like `employeeNumber`, `title`, `mobile`.

<figure><img src="/files/1TxwvYisF1r7rksLDnSc" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/G5mSjDxzDUFaZMRrkjfw" alt=""><figcaption></figcaption></figure>

## Group Mapping

To map LDAP groups:

1. Click **"Add mapper"** on the LDAP provider
2. Choose **"group-ldap-mapper"** as type

### Add configurations

<figure><img src="/files/o80l7vj4aDHZt2a89I5a" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/zbsdUcZOwRGtyr09tSmf" alt=""><figcaption></figcaption></figure>

### Sync Groups

Click on "Sync LDAP Groups with Keycloak" button to sync

<figure><img src="/files/e94vzd1zaQcrCi72PDwD" alt=""><figcaption></figcaption></figure>

### Verify Sync Groups in keycloak

<figure><img src="/files/q3w231RFwFNNTGTFaWvq" alt=""><figcaption></figcaption></figure>

LDAP Seed File group declaration

<figure><img src="/files/JaYWmMUZ4eAw8rBKQrrX" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="/files/WHy7TSvgMsPu1sYYCWqx" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/MwsJEY6ZOQdR3KtA8oVF" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.pranaypourkar.co.in/the-programmers-guide/identity-and-access-management-iam/keycloak/user-federation/integrating-openldap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.