Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

Configuring Keycloak with LDAP / Active Directory

Keycloak supports user federation with LDAP-compatible directories, including Microsoft Active Directory (AD), OpenLDAP, and other LDAP v3 servers. This guide walks through connecting Keycloak to an LDAP provider, mapping user attributes, and keeping users in sync.

Prerequisites

  • A running Keycloak instance (v21+)
  • Admin access to the Keycloak Admin Console
  • LDAP server hostname, port, and a bind account with read access to user entries
  • (Optional) TLS certificate for your LDAP server if using LDAPS

1. Add an LDAP Provider

  1. Log in to the Keycloak Admin Console and select your realm.
  2. Navigate to User Federation in the left sidebar.
  3. Click Add provider and select ldap from the dropdown.

You will be taken to the LDAP configuration form.

2. Connection Settings

Configure how Keycloak connects to your directory.

Field Description Example
Console Display Name A label shown in the Admin Console Corporate AD
Vendor Pre-fills sensible defaults for known servers Active Directory
Connection URL LDAP server address ldap://ad.example.com:389 or ldaps://ad.example.com:636
Enable StartTLS Upgrades a plain connection to TLS Off (use LDAPS instead when possible)
Bind Type Authentication method for the bind account simple
Bind DN Distinguished name of the service account cn=svc-keycloak,ou=ServiceAccounts,dc=example,dc=com
Bind Credential Password for the bind account (store securely)

After filling in the connection fields, click Test connection to verify Keycloak can reach the LDAP server, then click Test authentication to validate the bind credentials.

Active Directory example

Vendor:         Active Directory
Connection URL: ldaps://dc01.corp.example.com:636
Bind DN:        CN=svc-keycloak,OU=ServiceAccounts,DC=corp,DC=example,DC=com
Bind Credential: <password>

OpenLDAP example

Vendor:         Other
Connection URL: ldap://ldap.example.com:389
Bind DN:        cn=admin,dc=example,dc=com
Bind Credential: <password>

3. LDAP Search Settings

These settings control which entries Keycloak reads from the directory.

Field Description Example
Edit Mode Whether Keycloak can write back to LDAP READ_ONLY
Users DN Base DN under which user entries live OU=Users,DC=corp,DC=example,DC=com
Username LDAP attribute LDAP attribute mapped to Keycloak username sAMAccountName (AD) or uid (OpenLDAP)
RDN LDAP attribute Attribute used for the user's RDN cn
UUID LDAP attribute Unique, stable identifier per user objectGUID (AD) or entryUUID (OpenLDAP)
User Object Classes Comma-separated object classes to filter users person, organizationalPerson, user
User LDAP Filter Additional LDAP filter (optional) (memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com)
Search Scope Whether to search subtree or just one level Subtree
Read Timeout LDAP read timeout in milliseconds 30000
Pagination Enable LDAP result paging for large directories On

Tip — Limiting scope with a filter: If you only want a subset of AD users (e.g. members of a specific group) to be able to log in, use the User LDAP Filter field. This avoids importing the entire directory into Keycloak.

Edit Mode options

Mode Behaviour
READ_ONLY Keycloak reads from LDAP; no writes back. Password changes are blocked.
WRITABLE Keycloak can update user attributes and passwords in LDAP.
UNSYNCED Users are imported into Keycloak's local database; changes stay local.

For most enterprise setups, READ_ONLY is the safest starting point.

4. Kerberos / SSO (Optional)

If your Active Directory environment uses Kerberos, you can enable Kerberos integration on the same LDAP provider page. This allows desktop SSO for users on domain-joined machines. Refer to the Keycloak Kerberos documentation for the required krb5.conf and keytab setup.

5. Saving and Testing

Once the settings are filled in:

  1. Click Save.
  2. Scroll back to the top and click Synchronize all users to run an initial import.
  3. Navigate to Users in the sidebar and confirm that LDAP users appear in the list.

6. Attribute Mappers

Keycloak uses LDAP mappers to translate LDAP attributes into Keycloak user profile fields. After saving the provider, open the Mappers tab on the LDAP provider page. Several mappers are created automatically depending on the vendor you selected.

Common default mappers

Mapper name LDAP attribute Keycloak attribute
username sAMAccountName / uid username
first name givenName firstName
last name sn lastName
email mail email
creation date whenCreated createTimestamp

Adding a custom mapper

To map an additional LDAP attribute (e.g. department) to a Keycloak user attribute:

  1. Click Add mapper.
  2. Set Mapper Type to user-attribute-ldap-mapper.
  3. Set Name to something descriptive, e.g. department.
  4. Set User Model Attribute to the Keycloak attribute name (e.g. department).
  5. Set LDAP Attribute to the LDAP field name (e.g. department).
  6. Click Save.

Group mapper

To import LDAP groups into Keycloak:

  1. Click Add mapper.
  2. Set Mapper Type to group-ldap-mapper.
  3. Configure Groups DN to point to where your groups live, e.g. OU=Groups,DC=corp,DC=example,DC=com.
  4. Set Group Name LDAP Attribute to cn.
  5. Set Membership LDAP Attribute to member.
  6. Choose whether to use Drop non-existing groups during sync based on your needs.
  7. Click Save, then click Sync LDAP Groups to Keycloak.

7. Periodic Synchronization

Keycloak can automatically keep its local user cache in sync with the LDAP directory on a schedule.

Synchronization modes

Mode Description
Full sync Re-imports all LDAP users into Keycloak, reflecting additions, changes, and deletions.
Changed users sync Only imports users whose LDAP modifyTimestamp has changed since the last sync. More efficient for large directories.

Configuring a sync schedule

  1. Open your LDAP provider configuration.
  2. Scroll to the Sync Settings section.
  3. Enable Periodic Full Sync and set the interval in seconds. For example, 86400 = once per day.
  4. Enable Periodic Changed Users Sync and set a shorter interval, e.g. 3600 = every hour.
  5. Click Save.
Periodic Full Sync:          On
Full Sync Period:            86400   (24 hours)

Periodic Changed Users Sync: On
Changed Users Sync Period:   3600    (1 hour)

Note: Changed users sync requires the LDAP server to support modifyTimestamp. Active Directory and OpenLDAP both support this. If your server does not, rely on full sync only.

Triggering a manual sync

At any time you can trigger a sync from the LDAP provider page:

  • Synchronize all users — full sync of all entries.
  • Synchronize changed users — incremental sync since last run.

You can also trigger a sync via the REST API:

# Full sync
curl -X POST \
  "https://keycloak.example.com/admin/realms/{realm}/user-storage/{provider-id}/sync?action=triggerFullSync" \
  -H "Authorization: Bearer <admin_token>"

# Changed users only
curl -X POST \
  "https://keycloak.example.com/admin/realms/{realm}/user-storage/{provider-id}/sync?action=triggerChangedUsersSync" \
  -H "Authorization: Bearer <admin_token>"

8. Connecting via LDAPS (TLS)

For production deployments, always use LDAPS (ldaps://) or StartTLS to encrypt traffic between Keycloak and your directory.

If your LDAP server uses a certificate from a private CA:

  1. Import the CA certificate into the Java truststore used by Keycloak:

    keytool -import -alias ldap-ca \
  -file /path/to/ca.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

  2. Restart Keycloak.

  3. Update the Connection URL to use ldaps:// and port 636.

Alternatively, configure a custom truststore in keycloak.conf:

https-trust-store-file=/opt/keycloak/conf/ldap-truststore.jks
https-trust-store-password=changeit

9. Troubleshooting

Symptom Likely cause Action
"Test connection" fails Wrong hostname, port blocked by firewall Check network access; try telnet <host> 389
"Test authentication" fails Incorrect Bind DN or password Verify credentials with ldapsearch
No users appear after sync Wrong Users DN or User Object Classes Check with an LDAP browser (e.g. Apache Directory Studio)
Users can log in but attributes are missing Mapper misconfiguration or missing LDAP attribute Review the Mappers tab; confirm the attribute exists on the user object
Sync job never runs Scheduled sync not saved, or Keycloak restarted before save Re-check Sync Settings and click Save again

To enable verbose LDAP logging, add the following to Keycloak's logging configuration:

quarkus.log.category."org.keycloak.storage.ldap".level=DEBUG

Further Reading