Configuring LDAP to Add Users to Percussion CMS

Percussion CM1 can import users from LDAP or Active Directory (AD). To import users from LDAP or Active Directory, you must first configure access to the LDAP or AD servers.

These configurations are stored in the file <InstallRoot>/rxconfig/LDAP/ldapserver.xml. The file includes two example configurations, one for Active Directory and one for a generic LDAP server.

To configure a connection, uncomment one of the example configurations and update the values of each property to match your LDAP or AD server. Save the file, then restart the server.
LDAP configuration includes the following properties:

host: The name or IP address of the machine where the LDAP or Active Directory server is installed.

port: The port of the LDAP or Active Directory server. The default value of this port in the example configurations is 389, the default LDAP/Active Directory port. You only need to change this value if you specify a different port for your LDAP/AD. For LDAPS / LDAP over SSL/TLS the standard port is 636.

user: The user name used to log in to the directory server. Specify the fully-qualified distinguished name of the user. The value of this property in the example Active Directory Configuration is CN=Administrator, the default admin user for Active Directory. The value of this property in the generic LDAP configuration is cn=Directory Manager, the default admin user for SunONE Directory Server.

password: The password for the user name used to connect to the directory server. The default value of this property in both configurations is “password”. Change it to match the password of your admin user. This property can be empty when modifying a configuration. If it is empty, the existing password will be used.

catalog: The type of cataloging being done. Options are:

shallow: only records immediately below the specified organizational unit are returned. This value is specified for the catalog property in the Active Directory example configuration.

deep: records from the organizational unit and all subtrees are returned. This value is specified for the catalog property in the generic LDAP example configuration.

objectAttributeName: The name of the attribute to use when authenticating the user logging into CM1. Changing the value of this property allows you to use a different attribute to authenticate the user, such as uid. In the Active Directory configuration, the value of this property is samaccountname, which is the default attribute used to log in to Windows. Using this attribute allows users to log in to CM1 using the same user name and password as they use to log in to Windows. In the generic configuration, the value of this property is cn.

emailAttributeName: The name of the attribute that stores the email address of each user. Enter the value that your LDAP configuration uses.

organizationUnit: The fully-qualified path to the organization unit from which to begin searches. The example configurations include hypothetical values. Change them to match your own organization unit definitions.

secure: When using secure LDAP over port 636 should be set to true.  False by default. 

Other than password, which can be empty, all properties must have a value.

You must restart the server for the configuration to take effect. Note that the server can only support one LDAP configuration at a time. If the configuration file includes multiple uncommented LDAP configurations, none will be read into the server when it starts. (The server will still start normally if the configuration file includes multiple configurations, it just will not include any LDAP configurations and you will not be able to query the LDAP/AD server, and users imported from these servers will not be able to log in.)

The value of the password property is removed when the configuration is read into the server. If the configuration cannot be read, the password is not removed.

Private Certificate Authorities and secure LDAP

When using LDAP using a private SSL certificate, or self signed certificate, this certificate must be added to the Trust Store in order for Percussion to successfully establish a secure handshake with the LDAP server.  This can be accomplished by adding the certificate in PEM format to the <InstallDir>/rxconfig/trusted_certificates folder and restarting the Percussion Service.  See Auto Importing Trusted Certificates section for more information on this his feature. 

Updating an LDAP/Active Directory Configuration

To update the configurations, modify the configuration file and restart the server. When the server is restarted, the changes will take effect.

Note that you can leave the password property empty when updating the configuration. The existing password will be used. You only need to include the password when updating the configuration if you need to change the password.  If we the password is present in the LDAP config file after restarting, that is an indication that there was an error in the current configuration that needs corrected. 

Removing an LDAP/Active Directory Configuration

To remove an LDAP or AD configuration, comment out the configuration in the configuration file and restart the server. The configuration will be removed from the server during restart.

Troubleshooting LDAP/Active Directory Configurations

If you have configured LDAP/AD but the import button is disabled on the user management page, there is likely a problem with the LDAP/AD configuration. Check the Percussion CM1 server terminal window on the server machine or the file <CM1root>/logs/AppServer/server.log for errors.

• If you see the error "Failed to connect to Directory Server: An unknown naming exception was caught. The error message was: host/port":
  • The host name may be incorrect. Confirm that the host you specified exists, that you have spelled the host correctly, or that you specified the IP address correctly.
  • The port may be incorrect. Confirm that you have specified the correct port for you LDAP/AD server.
• If you see the error "Failed to connect to Directory Server: An unknown naming exception was caught. The error message was: [LDAP: error code 32 - No Such Object]":
  • An invalid user may be specified in the user property. Check the user property and confirm that the name you specified is valid, is spelled correctly.
  • An invalid value may be specified in the organizationalUnit property. Confirm that you have specified an organizational unit that exists on your LDAP/AD server.
• If you see the error "Failed to connect to Directory Server: An unknown naming exception was caught. The error message was: [LDAP: error code 49 - Invalid Credentials]", the value of the password property is invalid. Correct the password.
• If you see the error "Failed to parse file: C:\rxinst\main\config\LDAP\ldapserver.xml. The file is invalid.":
  • The file includes more than one LDAP configuration. Only one LDAP configuration is supported. Comment out or remove one of the LDAP configurations in the file.
  • The value of the catalog property is something other than "shallow" or "deep". Only these two values are supported for this property; others are invalid. Note that the values are case-sensitive. If the value is "Shallow" or "Deep" (in other words, with capital letters), the configuration is invalid and will fail.

NOTE: If you are updating a configuration, and the updated configuration is invalid, the CM1 server will continue to use the last valid configuration that was stored in the server.