How do I configure LDAP user authentication (external authentication)?

Introduction to external authentication via LDAP

To set up/enable LDAP authentication

To change passwords for LDAP logins

To configure user access to Entuity servers at the server level (grant server access)

Introduction to external authentication via LDAP:

You can integrate Entuity servers into environments where LDAP authentication systems are already implemented. External authentication compares user sign-on details with the account details held in the external authentication system (LDAP). External authentication can work with a single Entuity server and multiple Entuity servers running local security databases.

When LDAP authentication is enabled, users will only be able to access Entuity with LDAP login details.

LDAP authentication in Entuity is managed from the External Authentication page, which is accessible via Main Menu > Administration > External Authentication.

Note, from the server selection dropdown in the top left of the External Authentication page, you can only access remote servers that are also running Entuity v21.0 upwards.

To set up/enable LDAP authentication:

To enable LDAP authentication, you will need to specify details on each of the four tabs on the External Authentication page:

• LDAP Servers
• LDAP Group Mapping
• Server Access
• LDAP Emergency Users

Note, if you click Enable LDAP under the LDAP Servers tab before you have completed the details under the other tabs, the LDAP authentication will be saved but will not work, and users will not be able to log in using their LDAP credentials.

LDAP Servers tab:

1. Navigate to the LDAP Servers tab of the External Authentication page.
2. Click Add Server at the top of the page (or via the Overflow Menu).
   
   
   
   
3. The Add LDAP Server form will open on the right of the page.
   
   

Server Details: In this section, you can specify the connection details that Entuity requires to connect to the LDAP server.

1. Specify whether to Authenticate using multiple servers. This is applicable if you have multiple LDAP servers added. If the first LDAP server goes down and you have enabled this option, then the next server will be considered for authentication in its place.
2. Specify the type of authentication server in the Server Type dropdown field, either Windows AD or OpenLDAP/LDAPv3.
3. Specify the Connection Method Security used, either None (when not using TLS), LDAPS (to use SSL), or Start TLS (to use TLS).
4. Specify the display name of the authentication server in Entuity in the Display Name field.
5. Specify the IP address or resolved name of the authenticating LDAP server in the IP Address/Host Name field.
6. Specify the port used by the LDAP server in the Port field.
7. Switch the Bind Username as DN toggle On if your LDAP server only supports the bind operation using the DN format, and you cannot construct a valid user DN using Entuity's expression formats. If you switch the toggle Off, Entuity will search the LDAP server for the username.
8. Specify the user account and password needed to access the LDAP server in the Lookup User and Lookup User Password fields. These are not necessary if the server supports anonymous login.
9. Specify the starting point for searches in the LDAP directory in the Base DN field.
10. Specify the domain name to use as the search base in the Domain Name field. This field is only available if you have selected Windows AD above.
11. User Name Attribute field:
    • if you selected Windows AD and switched Bind Username as DN to On, the User Name Attribute field will be locked to 'cn'. If the Bind Username as DN is Off, this field will be locked to 'sAMAccountName'.
    • if you selected OpenLDAP/LDAPv3 (and regardless of the Bind Username as DN setting), you can specify the User Name Attribute field as you wish, by default 'cn'.
12. Specify your preferred User Search Filter, by default '( Use Name Attribute = {1} )'. In this expression, {0} - fully qualified login name (e.g. john.doe@entuity.com), {1} = login name only (e.g. john.doe), and {2} = domain name (e.g. entuity.com).

Group Searching:

1. If the User Refers to Groups toggle is switched to On, Entuity will search for groups using the user's MemberOf attribute. If switched to Off, Entuity will search for groups based on Group Base DN and then which group's member contains the user.
2. If you selected OpenLDAP/LDAPv3 above, the Group Name Attribute field will be available, in which you can specify the attribute that determines how to search the groups. By default 'cn'.
3. If the User Refers to Groups toggle is switched to Off, you can specify the Group Member Attribute. By default 'member'.
4. Specify the domain base from which you search for groups in the Group Base DN field. If left empty, the search uses Base DN.
5. If the User Refers to Groups toggle is set to Off, the Group Search Filter field will appear, in which you can specify the group search filter. By default '( Group Member Attribute = {3} )'. In this expression,, {3} = User DN.
6. Specify the numbers of levels of parent groups a search will go (if the group is not found in the current parent group) in the Search Parent Groups (levels) field.
7. Switch the Search Nested Groups toggle to On to search for the group within all nested sub-groups.

Once you have specified your LDAP server details:

1. Click Test Connection at the top of the form. This will open the Test LDAP user details form, where in you can enter the Bind Username and Bind User Password of the LDAP user. You cannot save and add the LDAP server until you have validated the server connection in this manner.
   
   
   
   
   
   
2. An LDAP Test Result window will open, displaying the attribute list for the LDAP server.
   
   
   
   
3. Close this test window and then click Done in the top right of the form to save your changes, otherwise click Cancel.
4. The LDAP server will then appear in the table. Click Save at the top of the page (or via the Overflow Menu) to save your change, and then progress to the LDAP Group Mapping tab.
   
   

LDAP Group Mapping tab:

From the LDAP Group Mapping tab, you can map the user groups defined in Entuity to those groups defined on the LDAP server. This tab has a table listing the local groups defined on the Entuity server (Entuity Groups) and their current Mapping Condition (e.g., 'All users have access', 'None').

Select an Entuity group to which you want to match an LDAP group, and click Manage Mapping at the top of the page (or via the Overflow Menu) to open the Manage Mapping form:

1. Specify the LDAP users/group match operator, choosing from one of the following:
   • Match all of the following criteria (AND)
   • Match any of the following criteria (OR)
     
     
     
     
2. Click Add Mapping to open the Add Mapping form.
   
   
   
   
   1. From here you can choose to Match Category of either an LDAP User or LDAP Group.
      
      
      
      
   2. In the Expression field, specify the LDAP user or LDAP group for which the mapping is being created. E.g., if you have an LDAP user called 'testAdmin1', and you want to add map this user to the 'Administrators' Entuity group, you would open the Edit Mapping for the Administrators group and using 'Match all of the following criteria', specify 'testAdmin1'. This will then map testAdmin1 to the Entuity Administrators group.
      
      
      
      
3. Click Done to save your changes, otherwise click Cancel.

You can also remove a mapping by selecting a group from the table and clicking Remove Mapping at the top of the page (or via the Overflow Menu or right-click Context Menu).

A removal confirmation dialog will open. Click Yes to proceed with the removal.

Once you have made your mappings as required, click Save, and then navigate to the Server Access tab.

Server Access tab:

From the Server Access tab, you can specify how access to the Entuity server is controlled at an authentication level.

If instead you want to specify server access at the individual server level (e.g. if you want a user to have full access to one Entuity server but more restricted access to another), please see this section below.

You can either allow access for all users, or for specific users/groups. By default, server access is enabled for all users:

You enable access for as many users and group as you wish. To allow access for specific users/groups:

1. Click Add User or Add Group at the top of the page (or via the Overflow Menu).
   
   
   
   
2. Enter the LDAP user or group that you wish to give access to the Entuity server and add '@*' to the end of the user or group name that you are entering. In the below example, we have added the LDAP user 'testAdmin1', who now has access to the Entuity server:
   
   
   
   

To edit a particular entry, select the entry and click Edit at the top of the page (or via the Overflow Menu or right-click Context Menu).

To remove server access, select the entry and click Remove at the top of the page (or via the Overflow Menu or right-click Context Menu). A dialog will open, asking you to confirm your choice.

Once you have made your desired changes, click Save at the top of the page (or via the Overflow Menu) and proceed to the LDAP Emergency Users tab.

LDAP Emergency Users tab:

An LDAP emergency user profile allows you to log in to an Entuity server that is configured for external LDAP authentication. When enabled, the emergency user account is always available, but would usually be used when Entuity cannot communicate with an LDAP server. The emergency user profile is intended only for administrators, to be used when LDAP authentication is not functioning. There is no limit to the number of emergency users that you can add.

The emergency user account is maintained through and can also be managed by authtool.

To enable emergency users:

1. Click Add Emergency User at the top of the page (or via the Overflow Menu).
   
   
   
   
2. The Add Emergency User form will open on the right of the page.
   
   
   
   
3. Specify a username and password. Click Done in the top right of the form to save your changes, otherwise click Cancel.
4. The emergency user will appear in the table.
   
   
   
   
5. To edit the password of an emergency user, or remove the emergency user, select the emergency user and click Change Password or Remove Emergency User at the top of the page (or via the Overflow Menu).
   
   

Enabling LDAP:

Once you have specified the details under all four tabs, return to the LDAP Servers tab and click Enable LDAP at the top of the page (or via the Overflow Menu):

A confirmation dialog will open. If you are happy to proceed, click Yes to enable LDAP for this server.

To change passwords for LDAP logins:

LDAP users can change their password through the account administration page as they would if they were authenticated internally. Entuity will forward the request to the LDAP server.

When the password has expired, the user will be prompted to change their password upon login. Note, the password complexity rules specified for internal users will not be enforced for LDAP passwords, and must be configured on the LDAP server itself. LDAP servers can create their own password complexity, and there may be a conflict if they are different.

To configure user access to Entuity servers at the server level (grant server access):

Within multiple Entuity server installations, you may want to configure access permissions at the Entuity server level, rather than at the authentication service level. For example, you may want a user to have full access to one Entuity server but more restricted access to another Entuity server.

You can specify this under the Groups tab on the Account Management page. Please see this article for further help and information on this functionality.