Updating the LDAP registry file

To configure Performance Management 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.

1. 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 query starting location in the LDAP tree.

   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 query starting location in the LDAP tree.
   • 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.

2. (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.
3. (Optional) When Performance Management is integrated with LDAP, Performance Management deals with two forms of identifiers.

   Short username

   Users typically log in with a short username. The short username is associated with the userIdMap attribute value. For IBM Tivoli Directory Server, the short username is uid. For Microsoft Active Directory, the short username is sAMAccountName.

   Distinguished Names

   In Performance Management, Role Based Access Control uses Distinguished Names.

   For example, the uid or sAMAccountName for a user is testuser, but the Distinguished Name is

   CN=Test User,CN=users,dc=adtest,dc=mycity,dc=mycompany,dc=com

   In this example, there is a discrepancy between the first component of the Distinguished Name and the uid or sAMAccountName. When this occurs, you must uncomment and configure the loginProperty to map the two forms of identifiers correctly. The first identifier must be the userIdMap attribute value (uid or sAMAccountName) and second identifier must be cn.
4. (Optional) If your LDAP server has more than 4500 users, and you are unable to adjust userFilter 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.
5. 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" />.
6. 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:

      <!--include optional="false" location="${shared.config.dir}/basicRegistry.xml"/-->

   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.
7. 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 Performance Management user, see Changing the default apmadmin user.
   • 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 .