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

Connecting Keycloak to LDAP / Active Directory

Keycloak has built-in support for LDAP and Active Directory — no plugins, no scripting. You fill in a form, click Test connection, and your users are in. This page walks you through exactly that.

For the full reference, see the official Keycloak documentation.

What you'll need

  • Keycloak admin access
  • Your LDAP server address and port (389 for plain, 636 for LDAPS)
  • A service account (bind DN + password) with read access to user entries
  • The base DN where your users live

Setting it up

  1. In the Keycloak Admin Console, go to your realm → User Federation → Add provider → ldap.

  2. Fill in the connection details:

    Field What to put
    Vendor Active Directory or Other (OpenLDAP etc.) — this auto-fills sensible defaults
    Connection URL ldap://your-server:389 or ldaps://your-server:636
    Bind DN Your service account, e.g. CN=svc-keycloak,OU=ServiceAccounts,DC=corp,DC=example,DC=com
    Bind Credential The service account password
    Users DN Where your users live, e.g. OU=Users,DC=corp,DC=example,DC=com
    Username LDAP attribute sAMAccountName for AD, uid for OpenLDAP

  3. Click Test connection, then Test authentication — both should turn green.

  4. Click Save, then Synchronize all users.

That's it. Head to Users in the sidebar and you'll see your directory users already there.

Keeping users in sync

Keycloak can automatically pull in new and updated users on a schedule. In the Sync Settings section of your LDAP provider:

  • Enable Periodic Changed Users Sync — set to 3600 (every hour) to catch day-to-day changes quickly.
  • Enable Periodic Full Sync — set to 86400 (once a day) to catch deletions and anything that slipped through.
Periodic Changed Users Sync:  On  →  3600 s
Periodic Full Sync:           On  →  86400 s

You can also trigger either sync manually at any time from the same page.

Good to know

You don't need to read all of this to get started — but it's useful once you're in production.

Edit mode controls whether Keycloak can write back to LDAP. The default is READ_ONLY, which is the right choice for most setups. If you need Keycloak to update attributes or passwords in your directory, switch to WRITABLE.

Attribute mappers are created automatically based on the vendor you selected (first name, last name, email, etc.). If you need to map additional fields — like department or employeeID — go to the Mappers tab on the provider and add a user-attribute-ldap-mapper.

Group sync is available via a group-ldap-mapper. Point it at your Groups DN and Keycloak will mirror your LDAP groups as Keycloak groups.

LDAPS (TLS) is strongly recommended for production. If your server uses a private CA certificate, you'll need to import it into Keycloak's truststore — see the Keycloak TLS docs for the exact steps.

Filtering users — if you only want a subset of your directory (e.g. members of a specific AD group) to be able to log in, use the User LDAP Filter field: 

(memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com)

Troubleshooting

Problem Most likely cause Fix
Test connection fails Port blocked or wrong hostname Check firewall; try telnet your-server 389
Test authentication fails Wrong Bind DN or password Double-check credentials with ldapsearch
No users after sync Wrong Users DN or object classes Use an LDAP browser (e.g. Apache Directory Studio) to confirm the path
Attributes missing on users Mapper not configured Check the Mappers tab; make sure the LDAP attribute name matches exactly
Sync schedule not running Settings not saved before restart Re-open the provider, re-check Sync Settings, and Save again

For anything beyond this guide — custom auth flows, Kerberos SSO, connection pooling — the Keycloak Server Administration Guide is comprehensive and well-maintained.