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.
You will need the following information:
Authentication in LDAP?
Authorization in LDAP?
How to access LDAP, connectionURL, password, etc.
Does your server support Bind Mode? Comparison Mode? (Active Directory supports only Comparison Mode)
How to find users in LDAP
How to find roles (membership in groups) in LDAP
Tomcat running on Linux or Windows?
Access to semarchy.xml
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.
# You are welcome to use any LDAP browsing tool like JXplorer.
# This command line tool is one way of testing connectivity.
# sudo yum install openldap-clients
ldapsearch -x -LLL -h host.example.com -D CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc -w mypassword -b"dc=ad,dc=example,dc=com" -s sub "(objectClass=user)" givenName
Here's a typical set of information needed to access an LDAP server based on the connection test above succeeding:
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.)
Ensure that you have access to the server running Semarchy xDM. And make sure you can edit the file semarchy.xml.
Once you have completed the checklist and have all the information you need, then you are ready to configure xDM with this information.
Verify .jar files
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.
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.
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.