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
In your Userful Infinity account, navigate to Admin Center > User Management.
Click External authentication in the left pane.
Select LDAP integration.
Click Set up LDAP integration. The integration setup panel appears on the right side.
In the LDAP Configuration tab, add a name for your LDAP integration.
Select your LDAP vendor.
Username LDAP attribute: Enter the name of the LDAP attribute, which is mapped as the Userful 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 Userful.
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.
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’.
User Object Classes: Enter all values of LDAP objectClass attribute for users in LDAP separated by commas. For example, ‘inetOrgPerson’, ‘organizationalPerson’. Newly created Userful 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.
Connection URL: Enter the connection URL to your LDAP server.
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’.
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.
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.
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.
Bind DN: DN of the LDAP admin, which will be used by Userful authentication provider to access the LDAP server.
Bind credential: Password of the LDAP admin. This field is able to obtain its value from the vault, using the ${vault.ID} format.
Under Sync Settings, enter the details required to reconnect an external authentication.
Batch Size - Count of LDAP users to be imported from LDAP to Userful within a single transaction.
Periodic Full Sync - Enable periodic, full synchronization of LDAP users to Userful if required.
Periodic Changed Users Sync - Enable periodic synchronization of changed or newly created LDAP users to Userful if required. Note: To know the correct status of the LDAP integration at any time, use the Sync LDAP option or edit the integration and click Save.
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.
Click Save.
Non-updated user lists
If you have cache settings enabled on your local LDAP server (not to be confused with cache settings in step 17 above), Userful updates the user lists from your local LDAP cache. It means that if your local LDAP cache does not contain the latest data; for example, you removed a user, but your local cache does not update to reflect this change, you will see the removed user in the list that Userful displays under User Management.
To avoid errors in the users list, you can turn off cache settings on your local LDAP server. Therefore, Userful always updates the data directly from your database.
If you enable cache on your local LDAP server, select shorter cache invalidation intervals in your LDAP configuration form (options available in step 17 above) to help reduce errors.
LDAP Group Mapper
LDAP Groups DN: Enter the LDAP DN where groups of this tree are saved. For example 'ou=groups,dc=example,dc=org'
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'
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'
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'.
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'.
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'.
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.
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 Userful authentication provider DB.
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.
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.
Click Save.
Resume LDAP after restoring backup
If for any reason you had to backup and restore your system, please follow the instructions below to resume your LDAP configuration after restoring the backup:
Navigate to Admin Center > User Management.
Under External Authentication, select LDAP integration.
Click the three-dot menu next to your LDAP configuration and click Edit.
Enter the password in the Bind Credential field.
Click Save Changes.
Note: If you take a backup of a server, make changes to the original LDAP configuration after taking the backup, and try to restore the non-updated backup on a different server, the backup will not work and you will not be able to log in. However, if you try to restore the backup on the same server, you can log in and update the LDAP configuration.
Last updated