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	READ_ONLY: Users UNSYNCHED: Groups	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: OU=test,DC=test,DC=datical,DC=net
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. Off: 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

• Troubleshoot