Configuring Keycloak for active directory and LDAP integration

To create new users and user groups in the DMC:

  1. Navigate to the Keycloak tab and log into Keycloak with your username and password.
  2. In theUser Federation tab, select ldap from the Add provider drop-down menu.
  3. Provide the required LDAP configuration details. (see section below for more information).
  4. Select Save to see the list of users imported.

Tip: You can checkout the Troubleshoot topic for help.

Required LDAP configuration fields

In the Add user federation provider section, add the following required settings:

Tab Field Value Notes
Settings Edit Mode


Be sure to select UNSYNCHED if you are creating a group.
Settings Vendor Active Directory The LDAP provider you are using. Ensure that Active Directory is selected for Groups to work correctly.
Settings Username LDAP Attribute Attribute that contains the user name.

Set this value to username and then configure mappers to designate the desired attribute to map to it. If you want to create a group, select group-ldap-mapper.

See the Attribute Mappers section below for more information.

Settings RDN LDAP Attribute CN  
Settings Connection URL The connection URL to your LDAP server.

Usually of the following format: ldaps://LDAP_HOST:636

Select the Test Connection button to confirm.

Settings Users DN The full DN of the LDAP tree where your users are located.

This DN is the LDAP user parent.

Example: It would be CN=users,DC=example,DC=com assuming that your typical user has a DN like: uid=john,ou=users,dc=example,dc=com

This is not a group DN. You must specify a node that contains users.

Settings Bind type Simple  
Settings Bind DN DN of the administrative or service user that accesses the information to use.

Example: CN=Administrator,CN=Users,DC=demo,DC=example,DC=com

Group Example:

Settings Bind Credentials Password of LDAP admin

Select Test Authentication to test the Bind DN/Bind Credential pair. Continue if it passes.

  • If it fails, check the Keycloak log to find the reason. Run the following command: datical-control logs keycloak
  • If the reason is PKIX Path building failed, see note below on PKIX
Settings LDAP Filter Filter value

Used to filter the full list of users and groups in the "Users DN" node to just the users and groups you want to import into Keycloak.

  • Can use a filter like (mail=*) to only include users with an email address (excludes service account users)
  • Can filter based on groups or anything else you need
  Search Scope Subtree or One Level If the node listed in "Users DN" contains nested nodes with users, select "Subtree". Otherwise select "one level".
Settings and Mappers Other Attributes Default or as you need  

5. Once the LDAP provider is created, select it from the User federation.

6. Select the Mappers tab.

7. Select the Add mapper button.

8. Provide the required LDAP mapper configuration details in the Mappers tab. (see section below for more information).

9. Check in the DMC in User Settings to verify your users were imported correctly.

Required LDAP Mapper configuration fields

In the Add user federation provider section, add the following required settings:

Tab Field Value Notes
Mapper Name

Title of the mapper

Mapper Mapper type Map single attributes form LDAP user to attribute of UserModel in Keycloak DB

Note: The Mapper type for groups must be: group-ldap-mapper

Mapper Group Name LDAP Attribute Attribute that contains the group name.

This attribute is used in a group objects name and RDN group. A typical group/role object may have DN.

Example: dn=Group1,ou=groups,dc=example,dc=org

Mapper Group Object Classes group This is the Object class (or classes) of the group object. Divide by commas if more classes are necessary. Typically in LDAP deployment, this value appears like so:
groupOfNamesIn an Active Directory the value is usually group.
Mapper Preserve Group Inheritance On

This radio button allows you to decide whether group inheritance from LDAP should be propagated to Keycloak.
On: Default
Group inheritance is preserved into Keycloak but the group sync may fail if LDAP structure contains recursions or multiple parent groups per child groups.

All LDAP Groups will map as flat top-level groups in Keycloak.

Mapper Ignore Missing Groups On This radio button allows you to ignore missing groups in the group hierarchy. It should be on to ensure that groups are found successfully.
Mapper Membership LDAP Attribute member

When Membership Attribute Type is UID then Membership LDAP Attribute could typically be memberUid. The value will be member in all other scenarios.

Mapper Membership Attribute Type DN

DN: This LDAP group has it's members declared in form of their full DN.

Example: member: uid=hohn, ou=users,dc=example,dc=com.

UID means that LDAP group has members declared in form of pure user uids.

Example: UID: john

Mapper Membership User LDAP Attribute cn

It is the name of the LDAP attribute on the user, which is used for membership mappings. Used only if Membership Attribute Type is UID. For example if value of 'Membership User LDAP Attribute' is 'uid' and LDAP group has 'memberUid: john', then it is expected that particular LDAP user will have attribute 'uid: john' .

Mapper LDAP Filter   LDAP Filter adds additional custom filters to the whole query to retreive LDAP groups. Leave this empty if no additional filtering is needed and you want to retreive all groups from LDAP. Ensure each filter is contained within (parenthesis).
Mapper Mode READ_ONLY LDAP_ONLY means that all group mappings of users are retrieved from LDAP and are saved as LDAP.
READ_ONLY is Read-only LDAP mode where group mappings are retrieved from both LDAP and DB and merged together. New group joins are not saved to LDAP but to DB.
IMPORT is Read-only LDAP mode where group mappings are retrieved from LDAP just at the time when user is imported from LDAP and then they are saved to local keycloak DB.
Mapper User Groups Retreive Strategy LOAL_GROUPS_BY_MEMBER_ATTRIBUTE Specify how to retrieve groups of user.
LOAD_GROUPS_BY_MEMBER_ATTRIBUTE means that roles of user will be retrieved by sending LDAP query to retrieve all groups where 'member' is our user.
GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE means that groups of user will be retrieved from 'memberOf' attribute of our user. Or from the other attribute specified by 'Member-Of LDAP Attribute' .
LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY is applicable just in Active Directory and it means that groups of user will be retrieved recursively with usage of LDAP_MATCHING_RULE_IN_CHAIN Ldap extension.
Mapper Member of LDAP Attribute memberOf Used just when 'User Roles Retrieve Strategy' is GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE . It specifies the name of the LDAP attribute on the LDAP user, which contains the groups, which the user is member of. Usually it will be 'memberOf' and that's also the default value.

Note: All other fields in the Add user federation provider section may need values changed depending on your particular ADD configuration.

Attribute mappers

By default, Keycloak does not copy all attributes it sees in the Active Directory the Mappers tab in the user federation admin section to view mappings.

Default attribute mappings:

  • email mail
  • cn username

To use a value other than CN for logging in, modify the username LDAP Mapper. Set User Model Attribute to the name of the Active Directory field that contains the user name you want to use.

You can set it to whatever attribute is used for user logins in your environment. Examples:

  • sAMAccountName
  • email

Note on "PKIX Path Building Failed"

Active Directory servers may be secured using an organization-managed root certificate rather than a global certificate authority. The error is caused by Keycloak not recognizing the certificate.

To install the certificate into Keycloak, do the following:

  1. Run datical-control truststore import --host <AD server to connect to> --port <portnumber>
  2. Run datical-service stop keycloak
  3. Run datical-service up -d keycloak
  4. Log in to Keycloak again to test the Bind DN/DN Credentials pair.

Related Topics