Configuring your appliance to authenticate users with an LDAP directory

You can optionally use a Lightweight Directory Access Protocol (LDAP) directory to authenticate users with your IBM® WebSphere® DataPower® XC10 Appliance.

Before you begin

You must be assigned the Appliance administration permission to perform these steps.

Important: When you enable Lightweight Directory Access Protocol (LDAP) authentication, then the option to self register new users is disabled. If you want to self register, then you must disable LDAP and enable the option to Allow new users to create their own accounts. Remember, you automatically enroll with your own account when LDAP is enabled, if you can authenticate with the LDAP server. Therefore, you create your account just by logging into the appliance.

About this task

Using an LDAP server to authenticate users is optional. The user name attribute is used to authenticate the IBM WebSphere DataPower XC10 Appliance users with the LDAP directory. Users that are not in the LDAP directory cannot be authenticated except for the primary appliance administrator.

[Version 2.5 and later] You can configure WebSphere DataPower XC10 Appliance to authenticate to LDAP over an SSL connection. This is done by specifying a Lightweight Directory Access Protocol over SSL (LDAPS) URL for connection to the LDAP server. If LDAPS is used, the truststore for the appliance must be modified to trust the SSL certificate of the LDAP server. If that certificate was issued by a certificate authority, the root signer certificate for that certificate authority must be added to the appliance truststore. If the LDAP server SSL certificate is self signed, then the certificate itself must be added to the appliance truststore.

[Version 2.5 and later] When LDAP authentication is configured, any LDAP user ID that matches the configured base domain name and the configured search filter for users can authenticate to the appliance. Each user has the permissions and data grid access that is granted to that particular user and the permissions and data grid access that is granted to LDAP groups to which the user belongs. It is not necessary to add the individual user to the collective. All LDAP users also have the permissions and access that is granted to the Everyone group. You might want to add a user to the collective so that data grid access and permissions can be configured for the individual user.

When LDAP authentication is configured, you can only add LDAP groups to the collective. Access and permissions can be granted to specified groups.

When LDAP authentication is configured, you cannot use the administrative console for the appliance or appliance programming interfaces to add or delete members of a group. Group membership is managed with your LDAP directory administration tools.

For IBM WebSphere DataPower XC10 Appliance releases before V2.5, only those users specifically added to the collective are granted permissions and accesses. Support for generalized LDAP access is added in V2.5. For releases before V2.5, the appliance imports group memberships from LDAP when the group is added to the collective. The group is then maintained on the appliance, and the membership might diverge from what was stored in LDAP. Beginning with V2.5, if LDAP authentication is configured group memberships are always resolved by querying the LDAP server.

Migration considerations: In a collective that includes V2.5 along with appliances that run earlier firmware versions, users that are in LDAP but not stored on the appliance collective cannot access restricted resources on the devices with the older firmware. Therefore, clients can only use the user IDs that are added to the appliance collective until all devices are upgraded.

When a collective includes members that are running firmware versions that are older than V 2.5, it is possible that the group memberships as stored on the older appliances will have diverged from what is stored in LDAP. These inconsistencies might cause problems. For example, if a user ID is in a group that is stored on an older appliance and permissions and access are associated with that group, but the group does not exist in LDAP or the group membership as stored on the appliance differs from what is in LDAP, then that userid might not be able to access restricted resources on the new appliance. This behavior occurs because the V2.5 appliance is checking LDAP directly, and not any local version of group membership. When you migrate, ensure that any user IDs that are used to access appliance data have the necessary permissions and access associated with the individual user ID. Also verify that those user IDs represent members of the LDAP groups that have the required authorizations.

Procedure

Navigate to the Settings panel. Use one of the following methods:
- From the menu bar at the top of the WebSphere DataPower XC10 Appliance user interface, navigate to Appliance > Settings.
- From the Welcome page, click the Customize settings link in the Step 1: Set up the appliance section.
Expand Security.
Configure your appliance to authenticate users with an LDAP directory.
1. To enable LDAP authentication, select the check box next to Enable LDAP authentication. The Enable LDAP authentication check box is not selected by default. Selecting this check box enables WebSphere DataPower XC10 Appliance to use the specified LDAP server to authenticate users at login.
2. Enter the JNDI provider URL. Example for non-SSL LDAP:
```
ldap://mycompany.com:389/ 
```
  or
```
ldap://mycompany.com/ 
```
  If a port is not explicitly specified, the default port number is 389. Example for SSL LDAP:
```
ldaps://mycompany.com:636/ 
```
  or
```
ldaps://mycompany.com/ 
```
  If a port is not explicitly specified, the default port number is 636.
3. Enter the JNDI base DN (users). Example:
```
CN=users,DC=mycompany,DC=com
```
4. Enter the JNDI base DN (groups). Example:
```
DC=mycompany,DC=com
```
5. Enter the Search filter (users). Example:
```
(&(sAMAccountName={0})(objectcategory=user)) or uid={0}
```
  Note: A user ID is embedded in the place holder "{0}". "{0}" is replaced by the login user ID that you entered in the login screen.
6. Enter the JNDI security authentication. This field is optional unless your LDAP server does not permit anonymous LDAP queries. Example:
```
CN=Administrator,CN=users,DC=mycompany,DC=com
```
7. Enter the password. This field is the JNDI security credentials, and is optional unless your LDAP server does not permit anonymous LDAP queries.
Test the LDAP authentication settings that you configured. You can test the settings you used to configure authentication with an LDAP server. This section allows you to perform LDAP queries to look for specified users and groups.
1. Click Test LDAP authentication settings to expand this section.
2. To test a user name, enter a user name in the LDAP user name field, and click the associated Test LDAP query button. Example:
```
test_user@us.ibm.com
```
  If the query is successful, then a message is displayed as follows: Found LDAP User DN: <user information>. If the query is not successful, then an error message is displayed.
3. To test a group name, enter a group name in the LDAP group name field, and click the associated Test LDAP query button. Example:
```
Test Group
```
  If the query is successful, then a message is displayed as follows: Found LDAP Group DN: <user information>. If the query is not successful, then an error message is displayed.

Results

You have specified an LDAP directory for external authentication when accessing the user interface.

What to do next

Understanding how to control user access to different areas of your environment is an important part of your security solution. For more information, see Managing users and groups.