LDAP and AD Integration

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?
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.

Test connectivity
1 2 3 4 # 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:

1 2 3 connectionURL="ldap://host.example.com:389" connectionName="CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc" connectionPassword="mypassword"

With Active Directory these are more typical:

1 2 3 4 5 6 7 8 9 connectionURL="ldaps://aws-emea-vds11-eu.service.cloud.abc:636" connectionName="DOMAIN\InfosecTST" connectionPassword="mypassword" adCompat="true" connectionURL="ldap://ldap-corp1-emdc1.corp.com:3268" connectionName="username@corp.com" connectionPassword="mypassword" adCompat="true"

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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 # Example 1: Search the entire tree for users # userSearch for samAccountName is typical in Active Directory. userBase="dc=acme,dc=esc" userSearch="(samAccountName={0})" userSubtree="true" roleBase="ou=SECURITY GROUPS,ou=Groups,dc=acme,dc=esc" roleSearch="(member={0})" roleName="cn" # Example 2: Search within a specified Organizational Unit for users # userSearch for samAccountName is typical in Active Directory. userBase="OU=RoncoInc,DC=ronco,DC=priv" userSubtree="true" userSearch="(sAMAccountName={0})" userRoleName="memberOf" roleBase="OU=Web Applications,OU=Ronco Groups,OU=Users,OU=Ronco,DC=ronco,DC=priv" roleSearch="(member={0})" roleName="CN" roleSubtree="false" # Example 3: Lookup users with a specified pattern userPattern="uid={0},ou=people,dc=example,dc=com" userRoleAttribute="uid" roleBase="ou=groups,dc=example,dc=com" roleName="cn" roleSearch="(memberUid={2})" roleSubtree="true"



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.

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

  • 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 <!-- # Example 1: Search the entire tree for users --> <Realm className="org.apache.catalina.realm.JNDIRealm" connectionURL="ldap://host.example.com:389" connectionName="CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc" connectionPassword="mypassword" adCompat="true" userBase="dc=acme,dc=esc" userSearch="(samAccountName={0})" userSubtree="true" roleBase="ou=SECURITY GROUPS,ou=Groups,dc=acme,dc=esc" roleSearch="(member={0})" roleName="cn" /> <!-- # Example 2: Search within a specified Organizational Unit for users --> <Realm className="org.apache.catalina.realm.JNDIRealm" connectionURL="ldap://host.example.com:389" connectionName="CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc" connectionPassword="mypassword" adCompat="true" userBase="OU=RoncoInc,DC=ronco,DC=priv" userSubtree="true" userSearch="(sAMAccountName={0})" userRoleName="memberOf" roleBase="OU=Web Applications,OU=Ronco Groups,OU=Users,OU=Ronco,DC=ronco,DC=priv" roleSearch="(member={0})" roleName="CN" roleSubtree="false" /> <!-- # Example 3: Lookup users with a specified pattern --> <Realm className="org.apache.catalina.realm.JNDIRealm" connectionURL="ldap://host.example.com:389" connectionName="CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc" connectionPassword="mypassword" userPattern="uid={0},ou=people,dc=example,dc=com" userRoleAttribute="uid" roleBase="ou=groups,dc=example,dc=com" roleName="cn" roleSearch="(memberUid={2})" roleSubtree="true" /> <!-- # Example 3: With Role Mapping included and tomcat-users.xml available as well --> <Realm className="com.semarchy.tool.jee.tomcat.RoleMappingRealm"> <Realm className="com.semarchy.tool.jee.tomcat.JNDIRealm" connectionURL="ldap://D03DCPRD03.corp.esc:389" connectionName="CN=Argo_ldapqueryqa,OU=Service Accounts,DC=corp,DC=esc" connectionPassword="mypassword" connectionTimeout="30000" authentication="simple" adCompat="true" referrals="ignore" userBase="dc=corp,dc=esc" userSearch="(samAccountName={0})" userSubtree="true" roleBase="ou=SECURITY GROUPS,ou=Groups,dc=corp,dc=esc" roleSearch="(member={0})" roleName="cn" roleSubtree="true"> </Realm> <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> </Realm>



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.

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
1 2 3 4 5 6 7 8 9 10 11 12 ... 5semarchy.org.apache.juli.AsyncFileHandler.level = FINE ... org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = INFO ... # From Semarchy # enable realm logging #org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL #org.apache.catalina.realm.level = ALL #org.apache.catalina.realm.useParentHandlers = true #org.apache.catalina.authenticator.level = ALL #org.apache.catalina.authenticator.useParentHandlers = true



Edited Logging Configuration

Example of the edited logging configuration
1 2 3 4 5 6 7 8 9 10 11 12 13 ... 5semarchy.org.apache.juli.AsyncFileHandler.level = ALL ... org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL ... # From Semarchy # enable realm logging org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL org.apache.catalina.realm.level = ALL org.apache.catalina.realm.useParentHandlers = true org.apache.catalina.authenticator.level = ALL org.apache.catalina.authenticator.useParentHandlers = true com.semarchy.tool.jee.tomcat.level = ALL



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

Standard product documentation in the Installation Guide is here: https://www.semarchy.com/doc/semarchy-xdm/semng.html#delegating-authentication-and-authorization-in-tomcat