Updating the LDAP registry file

Edit online

To configure Cloud APM to use LDAP for user authentication, update the ldapRegistry.xml file with your LDAP server information and then update the commonRegistry.xml to reference ldapRegistry.xml.

Before you begin

If you are configuring using SSL, to enable SSL communication between Cloud APM and LDAP, the Signer certificate for the LDAP server must be added to the Cloud APM server.

Procedure

Update the ldapRegistry.xml in the install_dir/wlp/usr/shared/config/ directory. Choose the Non-SSL or SSL template. Both are identical except for the additional SSL settings. Samples are available in ldapregistry.xml samples.
The following list describes the fields that must be updated and the fields that might need to be updated depending on your environment:
Fields that must be updated for IBM Tivoli Directory Server
- realm – This can be any name without spaces or special characters. The same realm name is specified in the ldapRegistry.xml and oauthVariables-onprem.xml files.
- host – The host name or the IP address of the LDAP server.
- port – The port number of the LDAP server. By default, the LDAP server uses port 389 for non-SSL, and 636 for SSL.
- baseDN - The starting point in the LDAP directory where the LDAP server should start searching for your users and groups. The Cloud APM server treats user distinguished names as case sensitive strings when performing role based authorization. Since user distinguished names include the baseDN, the baseDN value is case sensitive even if the ignoreCase property is set to true in the ldapRegistry.xml file. The baseDN must match the format in your LDAP directory.
- bindDN - The fully qualified DN, which has the authority to bind to your LDAP server and perform the requested queries. If your LDAP server allows anonymous queries, this field is not required.
- bindPassword - The password for bindDN. If your LDAP server allows anonymous queries, this field is not required.
Fields that might need to be updated for IBM Tivoli Directory Server (check with your LDAP administrator)
- userFilter and groupFilter - Check with your LDAP administrator to verify that the objectclass for userFilter and groupFilter are correct.
Fields that must be updated for Microsoft Active Directory
- realm – This can be any name without spaces or special characters. The same realm name is specified in the ldapRegistry.xml and oauthVariables-onprem.xml files.
- host – The host name or the IP address of the LDAP server.
- port – The port number of the LDAP server. By default, the LDAP server uses port 389 for non-SSL, and 636 for SSL.
- baseDN - The starting point in the LDAP directory where the LDAP server should start searching for your users and groups. The Cloud APM server treats user distinguished names as case sensitive strings when performing role based authorization. Since user distinguished names include the baseDN, the baseDN value is case sensitive even if the ignoreCase property is set to true in the ldapRegistry.xml file. The baseDN must match the format in your LDAP directory.
- bindDN – The fully qualified DN, which has the authority to bind to your LDAP server and perform the requested queries. If your LDAP server allows anonymous queries, this field is not required.
- bindPassword – The password for bindDN. If your LDAP server allows anonymous queries, this field is not required.
Fields that might need to change for Microsoft Active Directory (check with your LDAP administrator)
- userFilter and groupFilter - Check with the LDAP administrator to verify that the objectcategory for userFilter and groupFilter are correct.
(Optional) To encode the value of the bindPassword property in the ldapRegistry.xml file, run the securityUtility from the install_dir/wlp/bin directory. Enter the bindPassword password as an argument from the command line or when prompted. The securityUtility then outputs the encoded value. Copy the encoded value, and use that value for the bindPassword password in the ldapRegistry.xml file.
Comment out the login property line from the ldapRegistry.xml file if it exists and is enabled.
Active Directory: comment out <loginproperty>sAMAccountName;cn</loginProperty>
Tivoli Directory Service: comment out <loginProperty>uid;cn</loginProperty>
(Optional) If your LDAP directory contains thousands of users, use the userFilter parameter to limit the number of users that are returned when the Cloud APM server requests the list of users from the LDAP server. Specify a filter that returns the set of users that may require access to the Cloud APM console. If you do not specify a userFilter, when there are a very large number of users, the Cloud APM console displays the message "Failed to load Users" when you select Individual Users on the Role Based Access Control page.
If your LDAP directory contains thousands of groups, you should also use the groupFilter parameter to reduce the number of groups that are returned when the Cloud APM server requests the list of groups from the LDAP server. If you do not specify a groupFilter, when there are a very large number of users, the Cloud APM console displays the message "Failed to load Groups" when you select User Groups on the Role Based Access Control page.

If you only want users in certain LDAP groups to access the Cloud APM console, you can specify (memberOf=groupDN) in the userFilter where groupDN is the group distinguished name. If you want to include a nested LDAP group in the userFilter value, then you must include memberOf with the parent group DN and memberOf for each child group DN in the userFilter value. If you only specify memberOf with the parent group DN, then users in the child groups cannot log into the Cloud APM console.
This example shows a filtering on groups when a Microsoft Active Directory server is used:
```
userFilter="(&amp;(sAMAccountName=%v)(objectcategory=user)(|(memberOf=cn=Admins,ou=Groups,dc=mycity,dc=mycompany,dc=com)(memberOf=cn=Operators,ou=Groups,dc=mycity,dc=mycompany,dc=com)))"
groupFilter="(&amp;(cn=%v)(objectcategory=group)(|(cn=Admins,ou=Groups,dc=mycity,dc=mycompany,dc=com)(cn=Operators,ou=Groups,dc=mycity,dc=mycompany,dc=com)))"
userIdMap="user:sAMAccountName"
groupIdMap="*:cn"
groupMemberIdMap="memberOf:member"
```
This example shows filtering on uid and department:
```
               
    userFilter="(&amp;(uid=%v)(dept=CNNA)(objectclass=ibmPerson)))"               
    groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))"               
    userIdMap="*:uid"               
    groupIdMap="*:cn"               
    groupMemberIdMap="groupOfNames:member;groupOfUniqueNames:uniqueMember"
```
This example shows filtering on uid or emailaddress, and department. This means either the uid or emailaddress can be used in 'userIdMap' for login:
```
    userFilter="(&amp;((|(emailaddress=%v)(uid=%v))(dept=CNNA)(objectclass=ibmPerson)))"               
    groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))"               
    userIdMap="*:emailaddress"               
    groupIdMap="*:cn"               
    groupMemberIdMap="groupOfNames:member;groupOfUniqueNames:uniqueMember"
```
This example shows filtering on country:
```
userFilter="(&amp;(uid=%v)(c=us)(objectclass=ibmPerson)))"               
    groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))"               
    userIdMap="*:uid"               
    groupIdMap="*:cn"               
    groupMemberIdMap="groupOfNames:member;groupOfUniqueNames:uniqueMember"
```
(Optional) To reduce the number of users returned in the search results, uncomment the federatedRepository property, and edit the maxSearchResults and searchTimeOut parameters. If you fail to edit the maxSearchResults parameter, you might get a Not Authorized message when you attempt to access users and user groups in the Role Based Access Control window. In addition, you might see MaxResultsExceededException in your log files.
Update the realm name in the oauthVariables-onprem.xml file in the install_dir/wlp/usr/shared/config/ directory so that it matches the realm name in the ldapregistry.xml file. For example, if the ldapregistry.xml file has the following realm: <ldapRegistry id="ldap" realm="SampleLdapIDSRealm", then the oauthVariables-onprem.xml file should have the same realm as follows: <variable name="oauthRealm" value="SampleLdapIDSRealm" />.
Update the commonRegistry.xml file in the install_dir/wlp/usr/shared/config/ directory to use ldapRegistry.xml. Complete the following steps:
1. Comment out the line that refers to the basic registry as follows:
```

```
2. Remove the comment tags from the line that refers to the LDAP registry file as follows:
```
<include optional="false" location="${shared.config.dir}/ldapRegistry.xml"/>
```
3. Save the commonRegistry.xml file.
To verify that the configuration is complete, go to https://hostname:9443 and try logging in with the LDAP user account that will be the new Role Administrator.
- If you see the following message, your LDAP configuration is successful:
```
Not Authorized. You do not have permission to view this application. 
If you require access to this application, please send the URL that you are attempting to access to your monitoring administrator.
```
  The final step that you need to complete is to set the new Role Administrator user account from the LDAP repository as the default Cloud APM user, see Updating the primary role administrator.
- If you see the following message, your LDAP configuration failed:
```
login failed 
```
  You might need to revert to basic registry authentication and/or troubleshoot the LDAP configuration, see Troubleshooting the LDAP configuration .

Results

You configured Cloud APM to use LDAP for user authentication.

What to do next

After you change user authentication to LDAP, you need to change the primary role administrator user. For information on changing the default user, see Updating the primary role administrator.