Configure LDAP user access

note

You must have the admin role assigned to view the following Settings pages in the UI: LDAP Authentication, Access Control, API Access Control

info

Important. Secrets store UI property source

Clicking 'Apply' rewrites the LDAP config locally when configuring LDAP, Access Control and API Access Control. If you've configured a secrets store as a UI property source and reference any sensitive properties, remove the referenced properties from the local file and update them in your secrets store.

Manage user access using LDAP

Use a Lightweight Directory Access Protocol (LDAP) service to manage which users can access Data Migrator. If your LDAP service has user groups, you can use them to manage different access levels for signed-in users. For more information, see Manage LDAP user access control.

note

We refer exclusively to LDAP for brevity, although Microsoft's Active Directory (AD) is also supported.

Configure LDAP sign-in credentials for Data Migrator users in the UI

note

You may also configure LDAP authentication in the CLI. However, we recommend doing it in the UI as it lets you know if you've entered details incorrectly.

1. Sign in to the UI with your registered user account.
2. Select the settings cog on the upper-right to go to the Settings page.
3. Select LDAP Authentication from the submenu.
4. Select the Enable LDAP Authentication checkbox.
5. Fill in the LDAP server Configuration section with the authentication details for your LDAP Server:
   1. Enter the LDAP Server Hostname. This is the URL or hostname of your LDAP/AD server. For example, "hostname.com".
   2. Select the Use SSL checkbox if connecting to the LDAP service using Secure Sockets Layer (SSL).
   3. Check the Port is correct. The default is 389, or 636 if using SSL.
   4. To connect to the LDAP server without providing credentials, check Connect Anonymously. Only use this option if your LDAP server doesn't have an admin account, such as those used for testing.
   5. To connect to the LDAP server with credentials, enter the Administrator Bind Username, the distinguished name (DN) used to authenticate. For example, cn=administrator,dc=example,dc=com. Enter the corresponding Administrator Bind Password.
6. Select the Check Connection button to test your connection to the LDAP server. If valid, the following message will appear: "Your settings are valid and connection to the LDAP server was made." If you don't see this message, check your settings.

Add users to Data Migrator through LDAP

The User Search Configuration forms the query that polls your LDAP service for the user accounts that match the LDAP criteria you entered.

1. Enter the following:

   Base DN (Distinguished Name): This is the point in the LDAP tree where the search for users is performed. For example, dc=example,dc=com.

   note

   The Base DN is used for both Group and User searching. Consider the following structure: your groups are under ou=groups,dc=example,dc=com and your users are under ou=users,dc=example,dc=com. The Base DN needs to be dc=example,dc=com, the User Search Base should be ou=users, and the Group Search Base on the Access Control settings page should be ou=groups.

   User Search Base: (Optional) This is prepended onto the base DN to give the point in the LDAP tree where the user search will begin, for example, ou=engineering. Alternatively, you could leave the User Search Base empty and give ou=engineering,dc=example,dc=com or dc=example,dc=com as the Base DN.

   User Search Filter: This is the LDAP search filter used to match accounts. For example, (uid={0}).

   The {0} is replaced with the LDAP username that is used on the sign-in page. So (uid={0}) searches for a user where the uid matches the sign-in page username. A bind to the located user is then attempted using the corresponding sign-in password.

   You can give a User Search Filter specific enough to match the user, for example, (&(sAMAccountName={0})(objectClass=iNetOrgPerson)). The {0} is replaced for the value entered in the sign-in form. For the example LDAP users listed below, the sign-in value needs to match the sAMAccountName of john.smith and the object found needs to be iNetOrgPerson.

   Example LDAP User

   dn: cn=John Smith,ou=people,dc=example,dc=com
   objectClass: top
   objectClass: person
   objectClass: organizationalPerson
   objectClass: user
   objectClass: inetOrgPerson
   cn: John Smith
   sn: Smith
   givenName: John
   initials: JS
   distinguishedName: CN=John Smith,OU=people,DC=example,DC=com
   displayName: John Smith
   name: John Smith
   sAMAccountName: john.smith
   userPrincipalName: john.smith@example.com
   mail: john.smith@example.com
   ...

   Email Address Attribute: (Optional) This is the LDAP attribute for user email addresses. For example, "mail". This is used to display additional information in the UI.

   Full name attribute: (Optional) This is the LDAP attribute used for a user's full name. For example, "cn". This is used to display additional information in the UI.

2. The number of LDAP users that match your criteria is reported at the bottom of the screen. If this number matches your expectation, submit the settings using the Apply button.

   note

   IMPORTANT: Once submitted, these settings apply immediately. All signed-in users will be signed out.

3. Sign back in to the UI with your original registered user account. Return to the LDAP Authentication screen and confirm that the Enable LDAP Authentication checkbox is selected. You can manage user access in the next section, Manage LDAP user access control.

Manage LDAP user access control

Use the Access Control tab in the Settings submenu to manage the level of access for each LDAP user. Users must be assigned to LDAP groups in order to be given different privileges. These LDAP groups can then be mapped to the following Data Migrator role-based groups:

Role-based Group	Description
Admin Group	Users assigned to the Admin Group have full access to Data Migrator and may perform any configuration change.
Migration Manager	Users assigned to a Migration Manager Group may only configure migrations. They have no access to any other product settings.
Read Only	Read Only is an optional default role, enabled through the Default access to Read Only checkbox on the Access Control tab. If enabled, then all authenticate users that are not assigned to either an Admin Group or Migration Manager Group will automatically be added to the Read Only group.

When you sign in to the UI, your assigned role is listed on the upper-right side of the Dashboard along with your Data Migrator username.

Set up role-based access control

After LDAP is enabled and is successfully polling users, follow these steps to assign role-based access control:

1. Sign in to the UI using an admin account.

2. View the Access Control tab under Settings.

3. The Default access to Read Only checkbox is automatically selected. This is not required but is good practice as it ensures that matched LDAP users may sign in but they cannot make changes to Data Migrator until they are explicitly assigned to the Admin Group or Migration Manager Group.

4. Enter the LDAP Group Filter. This finds a group based on a user. Using (member={0}) will take the distinguished name (DN) of the signed-in user and search for a group containing that DN as one of the values of its "member" attribute. The located group is then evaluated against the rest of your settings to decide on the level of access for the user.

5. Enter a Group Name Attribute. This is the group name attribute that gets matched against the values entered for the role-based groups (Admin Groups, Migration Manager Groups, and Read-only Groups).
   
   For example:
   If you use "cn" and have a group search filter of (member={0}) and a user of cn=John,ou=engineer,dc=example,dc=com, you'll first find a group which contains "cn=John,ou=engineer,dc=example,dc=com" as a value for the "member" attribute. Assuming success, you'd find the group, cn=mygroup,ou=groups,dc=example,dc=com. You then take the "cn" of the group, for example, "mygroup", and match it against the values you entered for the different group roles. For example, assigning "mygroup" as a migration manager group will set its members with migration manager permissions.

6. Enter an LDAP Group Search Base (Optional). This sets the starting point in the directory tree for the search, for example, ou=admins,dc=example,dc=com.
   Assuming a Base DN of dc=example,dc=com, any of the following configurations would be permitted:

   • A Group Search Base of ou=subgroups,ou=groups and Base or Subtree search selected.
   • A Group Search Base of ou=groups and Subtree search selected.
   • A Group Search Base left empty and Subtree search selected.

7. Select either a Base or Subtree search. A Base search looks for groups in the immediate children of your base object. The Subtree search looks for groups more deeply as it searches all child objects and the base object.

8. Under Role Mapping, enter the attribute value for each LDAP group you want to map to the Data Migrator's admin groups or migration manager groups.

   note

   You must add attribute names one at a time.

9. Confirm that the expected number of users is retrieved for each group. If you get zero matches, check your filter settings. Once you confirm the correct numbers of users are matched, select + Add Admin Group and + Add Migration Manager Group, then select Apply. You can remove an attribute from the LDAP group by clicking on the trash icon beside it.

Changes to a user's privileges will apply when they next sign in.

Example LDAP Group

cn=admins,ou=subgroups,ou=groups,dc=springframework,dc=org

Attributes
objectclass: top
objectclass: groupOfUniqueNames
cn: admins
ou: admin
uniqueMember:
uid=rob@test.com,ou=people,dc=springframework,dc=org
uniqueMember:
uid=joe,ou=otherpeople,dc=springframework,dc=org

Using LDAPS

To use Lightweight Directory Access Protocol over SSL (LDAPS), you need a trusted certificate in the UI JVM truststore that matches the certificate presented by the LDAP server. By default, the Java virtual machine (JVM) running the UI uses a truststore called cacerts.

To use a self-issued LDAP server certificate, you must import the certificate for this private certificate authority into the cacerts file. See the Oracle documentation for steps to import a trusted certificate into a truststore.

LDAP/RBAC troubleshooting

Use the following steps to identify common LDAP and role-based access control issues.

Check the activity log to confirm that a user is assigned the expected role

1. Sign in to the UI with an admin account.

2. Go to Activity Log, under Settings.

3. Search by User, Role, or Action, selecting the role you want to confirm as assigned to users. Note that roles are assigned each time a user authenticates, so you may need to check the entry for the latest sign in.

note

You can view UI activity in the log file /var/log/wandisco/audit/ui.

Check LDAP settings

Verify the current LDAP settings by viewing /etc/wandisco/ui/application-prod.properties.

For example:

_application.ldap.baseDn=OU\=ldap-base,DC\=ldap-tld,DC\=internal_
_application.ldap.baseUrl=ldap\://your-ldap.server.url_
_application.ldap.userSearchFilter=mail\=*@email-address.com_
_application.ldap.mappings.fullName=cn_
_application.ldap.managerPassword=ENcodedPassWord_
_application.ldap.managerDn=ldap-tld\\Administrator_
_application.ldap.mappings.email=mail_
_application.ldap.enabled=true_

Configure LDAP authentication in the CLI

note

We recommend you configure LDAP authentication with the UI as the CLI doesn't let you know if you've entered your details incorrectly.

Configure a single LDAP user to sign in to the UI by using the encryptor tool:

1. On the UI host, run the following command:

   livedata-ui encryptor

2. Encrypt your LDAP manager password if you have one and save the encrypted string for step 4.

   livedata-ui encryptor
   10:59:22.425 [main] DEBUG com.wandisco.oneui.config.properties.util.AdditionalProperties
   FileUtil - Spring config additional location is set to: /etc/wandisco/ui/application-
   prod.properties
   
   1. Encrypt a string
   2. Encrypt and save a property to /etc/wandisco/ui/application-prod.properties
   3. Setup LDM Basic Auth
   4. Setup HVM Basic Auth
   5. Setup Livedata UI LDAP authentication
   6. Exit
   Please select an option:

   1. Select the Encrypt a string option when the menu appears.

   2. When the Please enter a string prompt appears, enter the password in plain text that you want to encrypt.

      The encrypted password string is then returned, for example: LvglJEyAySUQBuyUcEeRcYhzrJX6NMl0.

3. Select the Setup Livedata UI LDAP authentication option when the menu appears.

4. Enter your LDAP configuration.

   See the LDAP configuration properties for descriptions and examples of each property mentioned below.

   Values needed

   LDAP base url, (e.g. ldap://localhost): "application.ldap.baseUrl"
   LDAP port: "application.ldap.port"
   LDAP base dn: "application.ldap.baseDn"
   LDAP Manager dn:  (Optional, enter to skip) "application.ldap.managerDn"
   LDAP manager password: "application.ldap.managerPassword"
   Use LDAP bind auth? (y/n) "application.ldap.bindAuth"
   Password attribute. (Optional, enter to skip) "application.ldap.passwordAttribute"
   User dn patterns (Optional, enter to skip) "application.ldap.userDnPatterns"
   User search base (Optional, enter to skip) "application.ldap.userSearchBase"
   User search filter. (Optional, enter to skip) "application.ldap.userSearchFilter"
   Group search base. (Optional, enter to skip) "application.ldap.groupSearchBase"
   Group search filter. (Optional, enter to skip) "application.ldap.groupSearchFilter"

   Here are two examples of LDAP configuration:

   Example with LDAP bind auth and no Manager

   LDAP base url, (e.g. ldap://localhost): ldap://localhost
   LDAP port: 389
   LDAP base dn: dc=springframework,dc=org
   LDAP Manager dn:  (Optional, enter to skip)
   Use LDAP bind auth? (y/n) y
   User dn patterns (Optional, enter to skip) {0},ou=people
   User search base (Optional, enter to skip)
   User search filter. (Optional, enter to skip)
   Group search base. (Optional, enter to skip)
   Group search filter. (Optional, enter to skip)
   Example with password attribute and Manager

   LDAP base url, (e.g. ldap://localhost): ldap://localhost
   LDAP port: 389
   LDAP base dn: dc=springframework,dc=org
   LDAP Manager dn:  (Optional, enter to skip) CN=manager,OU=city,DC=example,DC=com
   LDAP manager password: LvglJEyAySUQBuyUcEeRcYhzrJX6NMl0
   Use LDAP bind auth? (y/n) n
   Password attribute. (Optional, enter to skip) userPassword
   User dn patterns (Optional, enter to skip)
   User search base (Optional, enter to skip) ou=people
   User search filter. (Optional, enter to skip) (uid={0})
   Group search base. (Optional, enter to skip)
   Group search filter. (Optional, enter to skip)

5. Select the Exit option once complete.

6. Restart the UI service. See System service commands - UI

LDAP configuration properties

The following properties will be written to the application-prod.properties file once LDAP has been configured. Use the descriptions and examples to help complete setup with the livedata-ui encryptor tool.

note

Don't configure these properties manually as the encryptor tool will handle special characters.

Name	Details
application.ldap.enabled	Enable LDAP sign-in for the UI. If set to false, the default will be regular authentication (defined when logging in to the UI for the first time). Default value: false Allowed values: true, false
application.ldap.baseUrl	The LDAP server base URL that includes the LDAP scheme, for example: ldap://myldapserver. Default value: (none) Allowed values: Any valid LDAP server base URL.
application.ldap.port	The LDAP server port, for example: 389. Default value: (none) Allowed values: An integer value between 1024 and 65535.
application.ldap.baseDn	The BaseDN for the LDAP search criteria, for example: dc=example,dc=com. Default value: (none) Allowed values: A comma-separated list of valid LDAP sub-tree entries.

Manager credentials

The manager credentials, used if the LDAP server has authentication enabled for read access.

Name	Details
application.ldap.managerDn	The distinguished name (DN) for the LDAP manager, for example: CN=manager,OU=city,DC=example,DC=com. Default value: (none) Allowed values: A comma-separated list of valid LDAP sub-tree entries.
application.ldap.managerPassword	The password of the LDAP manager. Encrypt the manager password using the encryptor tool before adding this value. Default value: (none) Allowed values: An encrypted password.

User authentication

Choose one of the following to use for user authentication with the LDAP server.

Name	Details
application.ldap.bindAuth	Enable the Bind Authenticator to match a specific user for authentication. If set to false, the passwordAttribute method is used by default. Default value: (none) Allowed values: true, false
OR
application.ldap.passwordAttribute	The LDAP attribute for the LDAP user password, for example: userPassword. The value for the user password on the LDAP server must be encrypted in bcrypt format. Default value: (none) Allowed values: Any valid LDAP attribute.

User match configuration

Choose between a user pattern or a search filter to match a valid LDAP user in the database.

Name	Details
application.ldap.userDnPatterns	The pattern to match the distinguished name (DN) for the user, for example: uid={0},ou=people. The {0} is used instead of the sign-in name that would normally exist here. Use this method if all of your users are stored under a single node in the directory. Default value: (none) Allowed values: Any valid Java pattern format relative to the application.ldap.baseDn defined earlier.
OR
application.ldap.userSearchBase	The distinguished name (DN) of the LDAP object from where to start the search for a user account, for example: ou=people. This field can be left blank if you want to start the search from the application.ldap.baseDn. Default value: (none) Allowed values: A valid LDAP DN relative to the application.ldap.baseDn defined earlier.
application.ldap.userSearchFilter	The LDAP query string to find the attribute representing the user account, for example (uid={0}). The value should be enclosed in brackets, and {0} is a required value as it is a token that represents the user account that will be validated. Default value: (none) Allowed values: A valid LDAP attribute to represent the user sign-in name.

Group match configuration (not required)

info

Group match configuration is not yet used by the UI as it applies to multiple user accounts (which is not yet supported).

Choose between a group pattern or a search filter to match a valid LDAP group in the database.

Name	Details
application.ldap.groupSearchBase	The distinguished name (DN) from where to start the search for an LDAP group, for example: ou=groups. This field can be left blank if you want to start the search from the application.ldap.baseDn. Default value: (none) Allowed values: A valid LDAP DN relative to the application.ldap.baseDn defined earlier.
application.ldap.groupSearchFilter	The filter to use to search for group membership, for example uniqueMember={0}. Default value: uniqueMember={0} Allowed values: A valid LDAP attribute to represent the user group membership.