Connecting Semarchy xDM to LDAP is common and useful. The difficulty that one faces is that different LDAP instances can be configured quite differently. So providing detailed steps is quite daunting. This document outlines all of the critical points to consider. You will need to provide the details about your LDAP environment in order to complete these steps.

Checklist

You will need the following information:

Authentication in LDAP

This is what nearly everyone means by, "I want to connect to LDAP." There is a centrally managed corporate Active Directory server (or other LDAP Server), and you want Semarchy xDM to accessed only by people defined in this LDAP server.

Authorization in LDAP

Should any authenticated user get access to xDM? Only users in a specified group?

You will need to map AD Groups to Semarchy Roles.

List the relevant AD Groups: ______, ______, ______, ...

List the relevant Semarchy Roles: semarchyConnect, semarchyAdmin, ______, ...

How to access LDAP

Test your ability to connect. Some LDAP servers are configured to allow anonymous access. Some are not. You'll need to gather up the details for your server.

Test from your xDM server to ensure that all details are correct and to be certain the LDAP server is accessible.

Test connectivity

Here's a typical set of information needed to access an LDAP server based on the connection test above succeeding:

With Active Directory these are more typical:

Note: The setting adCompat="true" prevents the error "javax.naming.PartialResultException: Unprocessed Continuation Reference(s);"

How to find users and roles in LDAP

Once you can connect, then you can submit an authorization request. The authorization request tells the server how to search the user hierarchy to look for users. The LDAP hierarchy can be very different at different companies. Here are some typical examples:

Semarchy can't really help you to know what values you need. It's a question for your internal LDAP or Active Directory team to help with.

While the above samples should be helpful, for systematic documentation about the configuration of this realm refer to the Tomcat Realm How To document.

Tomcat running on Windows

On Windows, it may make sense to use Waffle. (This is not possible on Linux.)

For documentation about the configuration of Waffle, refer to the WINDOWS AUTHENTICATION USING WAFFLE section of the Semarchy xDM Installation Guide.

Access to semarchy.xml

Ensure that you have access to the server running Semarchy xDM. And make sure you can edit the file semarchy.xml.

Configuring xDM

Once you have completed the checklist and have all the information you need, then you are ready to configure xDM with this information.

1. Verify .jar files

2. Edit semarchy.xml

3. Troubleshooting

Verify .jar files

If you have the groups "semarchyConnect" and "semarchyAdmin" and all other Semarchy roles defined directly in Active Directory, then users will pick up these roles during log in. Users who are part of these roles will be able to log in.

If you do not have these roles defined in Active Directory, then you'll need to map some existing groups to these roles. For example, all users in the group "MDM Developers" could get the roles "semarchyConnect" and "semarchyAdmin".
If you do not have the groups "semarchyConnect" and "semarchyAdmin" defined in your Active Director, then you need Semarchy's Tomcat tools to map the LDAP roles (groups) to Semarchy roles.

• If you are using Semarchy's pre-built AMI on AWS Marketplace or xDM - Preconfigured with Apache Tomcat, then this jar file is already in place for you.

• In cases where you installed Tomcat yourself, then you must add this jar file to Tomcat's lib directory.

Locate the jar file:

• Tomcat tools jar file: com.semarchy.tool.jee.tomcat-<version>.jar

  • Example: com.semarchy.tool.jee.tomcat-8.5.2-ga-20190111-1421.jar

• Find it inside the semarchy-xdm-install zip file here: mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-<version>.jar

  • Example: semarchy-xdm-install-4.4.4.ga-20190111-1421/mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-8.5.2-ga-20190111-1421.jar

• Place it in Tomcat's shared lib directory

  • Example: /usr/share/tomcat8/lib

  • Example: (TODO: list typical location on Windows)

Edit semarchy.xml

Make a backup. Edit. Restart tomcat.

Sample Realm configurations:

Realm Samples from semarchy.xml

Troubleshooting

Enable logging

Logging using an xDM installation that is not running on Semarchy's AWS Marketplace AMI:

You configure logging Tomcat's logging configuration file. In most environments, Tomcat's logging configurations are stored in the logging.properties file. In a standard Linux environment, this file lives in the /etc/tomcat8/ folder (there is an equivalent in Windows servers). Because there are different places you need to edit in the logging.properties file, it would be easier to take the file attached below and replace your current logging.properties file rather than manually adding the configurations and risk typos and human errors.

Open

Note: when you replace the original logging.properties file, be sure to change the file name from logging-enabled.properties to logging.properties.

Logging using an xDM installation that is running on Semarchy's AWS Marketplace AMI:

The AWS Marketplace AMI already seeded Tomcat's logging configuration to perform LDAP logging but the settings are not turned on to the levels you need to see meaningful logging. You will need to edit the logging.properties file in the /etc/tomcat8 folder to set logging to ALL and uncomment realm logging.

Edit the logging.properties file. Compare the original version to the edited version below to see the 3 places where you need to modify the Tomcat logging configurations:

Original Logging Configuration

Example of the original logging configuration

Edited Logging Configuration

Example of the edited logging configuration

Once logging is correctly configured, you need to restart Tomcat for the changes to take effect. Find the newly created logging file called realm-authenticator.log in the /var/log/tomcat8 folder (assuming you are on Linux). Catalina logs and localhost logs might contain relevant messages with detailed error.

Extra resources: The log4j levels documentation and a more user-friendly version. 

LDAP client tools: ...

Sample configuration files

aaa, bbb

Related articles