#Configure LDAP / Active Directory Federation

This guide walks through setting up LDAP or Microsoft Active Directory user federation in Keycloak, enabling users from your corporate directory to authenticate without migrating credentials.

For background concepts, see Identity Federation.

#Prerequisites

• A running Keycloak instance with admin access.
• Network connectivity from Keycloak Pods to the LDAP/AD server.
• An LDAP bind account with read access to the user directory (and write access if using WRITABLE edit mode).
• The LDAP base DN and user search filter for your directory structure.

#Step 1: Add the LDAP Provider

1. In the Admin Console, select the target Realm.
2. Go to User federation in the left navigation bar.
3. Click Add LDAP provider.
4. Configure the connection settings:

5. Click Test connection to verify connectivity.
6. Click Test authentication to verify bind credentials.

#Step 2: Configure User Search

#Edit Modes

#Step 3: Configure Synchronization

Synchronization imports user data from LDAP into Keycloak's local cache for faster lookups.

Click Save, then click Synchronize all users to perform the initial import.

Verify the import by going to Users and searching for LDAP users.

#Step 4: Configure LDAP Mappers

LDAP Mappers define how LDAP attributes are mapped to Keycloak user attributes, groups, and roles.

#Default Mappers

When the LDAP provider is created, Keycloak auto-creates several default mappers. Review them in the Mappers tab:

#Add a Group Mapper

To synchronize LDAP groups to Keycloak groups:

1. In the LDAP provider detail, click the Mappers tab.
2. Click Add mapper.
3. Select group-ldap-mapper.
4. Configure:

5. Click Save, then click Sync LDAP groups to Keycloak.

#Add a Role Mapper

To map LDAP groups directly to Keycloak Realm roles:

1. Click Add mapper > role-ldap-mapper.
2. Configure the LDAP roles DN, role object classes, and membership attributes (similar to group mapper).
3. Set Use Realm Roles Mapping to On.
4. Click Save and sync.

#Step 5: Configure LDAP over TLS

For production environments, always use encrypted LDAP connections.

#Option A: LDAPS (Recommended)

Use ldaps:// in the Connection URL (port 636):

ldaps://ldap.example.com:636

If the LDAP server uses a certificate signed by a custom CA, import the CA certificate into the Keycloak truststore. In a Kubernetes-managed deployment, mount the CA certificate and configure the JVM truststore via the Keycloak CR:

spec:
  additionalOptions:
    - name: spi-truststore-file-file
      value: /opt/keycloak/certs/truststore.jks
    - name: spi-truststore-file-password
      secret:
        name: keycloak-truststore-secret
        key: password
  unsupported:
    podTemplate:
      spec:
        containers:
          - volumeMounts:
              - name: truststore
                mountPath: /opt/keycloak/certs
        volumes:
          - name: truststore
            secret:
              secretName: keycloak-truststore

#Option B: StartTLS

Use ldap:// with StartTLS enabled (port 389):

ldap://ldap.example.com:389

Enable StartTLS in the LDAP provider configuration. The same CA certificate truststore configuration applies.

#Troubleshooting