LDAP Integration

Authenticate users using Lightweight Directory Access Protocol (LDAP). The platform allows a batch size of 1000 users to be imported from Active Directory/ Red Hat Directory Server in a single import transaction.

Audience

This guide is meant for LDAP server administrators.

Disabling group mapping and using filters

To set up the LDAP integration you need to add details for LDAP Configuration and LDAP Group Mapper. These are mandatory for versions until 12.8.2.

If you're using Userful Infinity Version 12.8.3 and above:

• You can enable or disable the LDAP Group Mapper.

• You can use filters to import users.

LDAP Configuration

1. In your Userful Infinity account, navigate to Admin Center > User Management.

2. Click External authentication in the left pane.

3. Select LDAP integration.

4. Click Set up LDAP integration. The integration setup panel appears on the right side.

5. In the LDAP Configuration tab, add a name for your LDAP integration.

6. Select your LDAP vendor.

7. Username LDAP attribute: Enter the name of the LDAP attribute, which is mapped as the Keycloak username. For many LDAP server vendors, it can be ‘uid’. For Active Directory it can be ‘sAMAccountNAme’ or ‘cn’. The attribute should be filled for all LDAP user records you want to import from LDAP to Keycloak.

8. RDN LDAP attribute: Enter the name of the LDAP attribute which is used as the RDN (top attribute) of typical user DN. This is usually the same as the Username LDAP attribute.

9. UUID LDAP attribute: Enter the name of the LDAP attribute which is used as a unique object identifier for objects in LDAP. For many LDAP server vendors, it is ‘entryUUID’, however some are different. For example, for Active Directory, it should be ‘objectGUID’. If your LDAP server does not support UUID, you can use another attribute that is unique among LDAP users in the tree. For example, ‘uid’ or ‘entryDN’.

10. User Object Classes: Enter all values of LDAP objectClass attribute for users in LDAP separated by commas. For example, ‘inetOrgPerson’, ‘organizationalPerson’. Newly created Keycloak users will be written to LDAP with all these object classes. Existing LDAP user records can be found only if they contain all these object classes. Note: You will see this field only in Userful Infinity versions 12.8.3 and above.

11. Connection URL: Enter the connection URL to your LDAP server.

12. Users DN: Enter the full DN of the LDAP tree where your users are. This DN is the parent of LDAP users. It could be for example ‘ou=users,dc=example,dc=com’ assuming that your typical user will have DN like ‘uid=’john’, ou=users,dc=example,dc=com’.

13. User LDAP filter: Enter additional LDAP filter for filtering searched users. You can leave this empty if you do not need an additional filter. Note: You will see this field only in Userful Infinity versions 12.8.3 and above.

14. Search scope: Select search scope. For one level, the search applies only for users in the DNs specified by User DNs. For subtree, the search applies to the whole subtree.

15. Bind Type: Select the type of authentication method used during LDAP bind operation. It is used in most of the requests sent to the LDAP server. Currently only ‘non’ (anonymous LDAP authentication) or ‘simple’ (bind credential + bind password authentication) mechanisms are available.

16. Bind DN: DN of the LDAP admin, which will be used by Keycloak to access the LDAP server.

17. Bind credential: Password of the LDAP admin. This field is able to obtain its value from the vault, using the ${vault.ID} format.

18. Under Sync Settings, enter the details required to reconnect an external authentication.

• Batch Size - Count of LDAP users to be imported from LDAP to Keycloak within a single transaction.

• Periodic Full Sync - Enable periodic, full synchronization of LDAP users to Keycloak if required.

• Periodic Changed Users Sync - Enable periodic synchronization of changed or newly created LDAP users to Keycloak if required.

17. Select cache settings.

• DEFAULT' applies the default settings for the global cache.

• 'EVICT_DAILY' lets you add a time at which the cache will be invalidated daily

• 'EVICT_WEEKLY' lets you add a time and day of the week at which the cache will be invalidated.

• 'MAX_LIFESPAN' lets you add time in milliseconds which will be the lifespan of a cache entry.

18. Click Save.

LDAP Group Mapper

1. LDAP Groups DN: Enter the LDAP DN where groups of this tree are saved. For example 'ou=groups,dc=example,dc=org'

2. Group Name LDAP Attribute: Name of LDAP attribute, which is used in group objects for name and RDN of group. Usually it will be 'cn' . In this case typical group/role object may have DN like 'cn=Group1,ou=groups,dc=example,dc=org'

3. Group Object Classes: Object class (or classes) of the group object. It's divided by comma if more classes are needed. In typical LDAP deployment it could be 'groupOfNames' . In Active Directory it's usually 'group'

4. Membership LDAP Attribute: Name of the LDAP attribute on a group, which is used for membership mappings. Usually it will be 'member'. However when 'Membership Attribute Type' is 'UID' then 'Membership LDAP Attribute' could be typically 'memberUid'.

5. Membership LDAP Type: DN means that the LDAP group has its members declared in the form of their full DN. For example 'member: uid=john,ou=users,dc=example,dc=com'. UID means that the LDAP group has its members declared in the form of pure user uids. For example 'memberUid: john'.

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

7. Group LDAP Filter: Adds an additional custom filter to the whole query to retrieve LDAP groups. Leave this empty if no additional filtering is needed and you want to retrieve all groups from LDAP. Otherwise make sure that filter starts with and ends with parentheses (<filter>). Note: You will see this field only in Userful Infinity versions 12.8.3 and above.

8. Select Mode.

• LDAP_ONLY: All group mappings of users are retrieved from LDAP and saved into LDAP.

• READ_ONLY: Read-only LDAP mode where group mappings are retrieved from both LDAP and DB and merged together. New group joinees are not saved to LDAP but to the DB.

• IMPORT: Read-only LDAP mode where group mappings are retrieved from LDAP only at the time when a user is imported from LDAP and they are saved to the local keycloak DB.

8. User Groups Retrieve Strategy: Specify how to retrieve groups of users.

• LOAD_GROUPS_BY_MEMBER_ATTRIBUTE: Roles of users will be retrieved by sending a LDAP query to retrieve all groups where 'member' is our user.

• GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE: Groups of users will be retrieved from the 'memberOf' attribute of our user, or from the other attribute specified by 'Member-Of LDAP Attribute'.

• LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY: Applicable only in Active Directory. This means that groups of users will be retrieved recursively with use of LDAP_MATCHING_RULE_IN_CHAIN LDAP extension.

8. Member-Of LDAP Attribute: Used only when the '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 the user belongs to. Usually it will be 'memberOf' and that's also the default value.

9. Click Save.