{"type":"doc","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"You will need the following information:","type":"text"}]},{"type":"taskList","attrs":{"localId":""},"content":[{"type":"taskItem","attrs":{"state":"TODO","localId":"1"},"content":[{"text":"Authentication in LDAP?","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"2"},"content":[{"text":"Authorization in LDAP?","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"3"},"content":[{"text":"How to access LDAP, connectionURL, password, etc.","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"8"},"content":[{"text":"Does your server support Bind Mode? Comparison Mode? (Active Directory supports only Comparison Mode)","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"4"},"content":[{"text":"How to find users in LDAP","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"5"},"content":[{"text":"How to find roles (membership in groups) in LDAP","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"6"},"content":[{"text":"Tomcat running on Linux or Windows?","type":"text"}]},{"type":"taskItem","attrs":{"state":"TODO","localId":"7"},"content":[{"text":"Access to semarchy.xml","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authentication in LDAP","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authorization in LDAP","type":"text"}]},{"type":"paragraph","content":[{"text":"Should any authenticated user get access to xDM? Only users in a specified group?","type":"text"}]},{"type":"paragraph","content":[{"text":"You will need to map AD Groups to Semarchy Roles.","type":"text"}]},{"type":"paragraph","content":[{"text":"List the relevant AD Groups: ","type":"text"},{"text":"______, ______, ______, ...","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"List the relevant Semarchy Roles: ","type":"text"},{"text":"semarchyConnect, semarchyAdmin, ______, ...","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How to access LDAP","type":"text"}]},{"type":"paragraph","content":[{"text":"Test your ability to connect","type":"text","marks":[{"type":"link","attrs":{"href":"https://serverfault.com/questions/452935/how-to-test-a-ldap-connection-from-a-client"}}]},{"text":". Some LDAP servers are configured to allow anonymous access. Some are not. You'll need to gather up the details for your server.","type":"text"}]},{"type":"paragraph","content":[{"text":"Test from your xDM server to ensure that all details are correct and to be certain the LDAP server is accessible.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Test connectivity","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"# You are welcome to use any LDAP browsing tool like JXplorer.\n# This command line tool is one way of testing connectivity.\n# sudo yum install openldap-clients\nldapsearch -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","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Here's a typical set of information needed to access an LDAP server based on the connection test above succeeding:","type":"text"}]},{"type":"codeBlock","content":[{"text":"connectionURL=\"ldap://host.example.com:389\"\nconnectionName=\"CN=ldapuser1,OU=Service Accounts,DC=acme,DC=esc\"\nconnectionPassword=\"mypassword\"","type":"text"}]},{"type":"paragraph","content":[{"text":"With Active Directory these are more typical:","type":"text"}]},{"type":"codeBlock","content":[{"text":"connectionURL=\"ldaps://aws-emea-vds11-eu.service.cloud.abc:636\"\nconnectionName=\"DOMAIN\\InfosecTST\"\nconnectionPassword=\"mypassword\"\nadCompat=\"true\"\n\nconnectionURL=\"ldap://ldap-corp1-emdc1.corp.com:3268\"\nconnectionName=\"username@corp.com\"\nconnectionPassword=\"mypassword\"\nadCompat=\"true\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Note: The setting adCompat=\"true\" prevents the error \"javax.naming.PartialResultException: Unprocessed Continuation Reference(s);\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How to find users and roles in LDAP","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","content":[{"text":"# Example 1: Search the entire tree for users\n# userSearch for samAccountName is typical in Active Directory.\nuserBase=\"dc=acme,dc=esc\"\nuserSearch=\"(samAccountName={0})\"\nuserSubtree=\"true\"\nroleBase=\"ou=SECURITY GROUPS,ou=Groups,dc=acme,dc=esc\"\nroleSearch=\"(member={0})\"\nroleName=\"cn\"\n\n# Example 2: Search within a specified Organizational Unit for users\n# userSearch for samAccountName is typical in Active Directory.\nuserBase=\"OU=RoncoInc,DC=ronco,DC=priv\"\nuserSubtree=\"true\"\nuserSearch=\"(sAMAccountName={0})\"\nuserRoleName=\"memberOf\"\nroleBase=\"OU=Web Applications,OU=Ronco Groups,OU=Users,OU=Ronco,DC=ronco,DC=priv\"\nroleSearch=\"(member={0})\"\nroleName=\"CN\"\nroleSubtree=\"false\"\n\n# Example 3: Lookup users with a specified pattern\nuserPattern=\"uid={0},ou=people,dc=example,dc=com\"\nuserRoleAttribute=\"uid\"\nroleBase=\"ou=groups,dc=example,dc=com\"\nroleName=\"cn\"\nroleSearch=\"(memberUid={2})\"\nroleSubtree=\"true\"","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"While the above samples should be helpful, for systematic documentation about the configuration of this realm refer to the ","type":"text"},{"text":"Tomcat Realm How To","type":"text","marks":[{"type":"link","attrs":{"href":"http://tomcat.apache.org/tomcat-8.5-doc/realm-howto.html#JNDIRealm"}}]},{"text":" document.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tomcat running on Windows","type":"text"}]},{"type":"paragraph","content":[{"text":"On Windows, it may make sense to use Waffle. (This is not possible on Linux.)","type":"text"}]},{"type":"paragraph","content":[{"text":"For documentation about the configuration of Waffle, refer to the ","type":"text"},{"text":" WINDOWS AUTHENTICATION USING WAFFLE","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.semarchy.com/doc/semarchy-xdm/semng.html#windows-authentication-using-waffle"}}]},{"text":" section of the Semarchy xDM Installation Guide. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Access to semarchy.xml","type":"text"}]},{"type":"paragraph","content":[{"text":"Ensure that you have access to the server running Semarchy xDM. And make sure you can edit the file semarchy.xml.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Configuring xDM","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you have completed the checklist and have all the information you need, then you are ready to configure xDM with this information.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Verify .jar files","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Edit semarchy.xml","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Troubleshooting","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Verify .jar files","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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\". ","type":"text"},{"type":"hardBreak"},{"text":"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.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you are using Semarchy's pre-built ","type":"text"},{"text":"AMI on AWS Marketplace","type":"text","marks":[{"type":"link","attrs":{"href":"https://aws.amazon.com/marketplace/pp/B00M8OLI8E"}}]},{"text":" or ","type":"text"},{"text":"xDM - Preconfigured with Apache Tomcat","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"link","attrs":{"href":"https://www.semarchy.com/all-downloads/"}}]},{"text":", then this jar file is already in place for you.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In cases where you installed Tomcat yourself, then you must add this jar file to Tomcat's lib directory.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]}]}]}]},{"type":"paragraph","content":[{"text":"Locate the jar file:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tomcat tools jar file: com.semarchy.tool.jee.tomcat-.jar","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: com.semarchy.tool.jee.tomcat-8.5.2-ga-20190111-1421.jar","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Find it inside the semarchy-xdm-install zip file here: mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-.jar","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"semarchy-xdm-install-4.4.4.ga","type":"text","marks":[{"type":"link","attrs":{"href":"http://semarchy-xdm-install-4.4.4.ga"}}]},{"text":"-20190111-1421/mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-8.5.2-ga-20190111-1421.jar","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Place it in Tomcat's shared lib directory","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: /usr/share/tomcat8/lib","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: (TODO: list typical location on Windows)","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Edit semarchy.xml","type":"text"}]},{"type":"paragraph","content":[{"text":"Make a backup. Edit. Restart tomcat.","type":"text"}]},{"type":"paragraph","content":[{"text":"Sample Realm configurations:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Realm Samples from semarchy.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n \n\n\n\n\n\n\n\n\n \n \n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Enable logging","type":"text"}]},{"type":"paragraph","content":[{"text":"Logging using an xDM installation that is ","type":"text","marks":[{"type":"strong"}]},{"text":"not","type":"text","marks":[{"type":"underline"},{"type":"strong"}]},{"text":" running on Semarchy's AWS Marketplace AMI:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You configure logging Tomcat's logging configuration file. In most environments, Tomcat's logging configurations are stored in the ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file. In a standard Linux environment, this file lives in the ","type":"text"},{"text":"/etc/tomcat8/","type":"text","marks":[{"type":"code"}]},{"text":" folder (there is an equivalent in Windows servers). Because there are different places you need to edit in the ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file, it would be easier to take the file attached below and replace your current ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file rather than manually adding the configurations and risk typos and human errors.","type":"text"}]},{"type":"mediaGroup","content":[{"type":"media","attrs":{"id":"b62f5838-b8e4-4883-a00e-032dd8470d01","collection":"contentId-602931263","type":"file"}}]},{"type":"paragraph","content":[{"text":"Note: when you replace the original ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file, be sure to change the file name from ","type":"text"},{"text":"logging-enabled.properties","type":"text","marks":[{"type":"code"}]},{"text":" to l","type":"text"},{"text":"ogging.properties.","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Logging using an xDM installation that is running on Semarchy's AWS Marketplace AMI:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file in the ","type":"text"},{"text":"/etc/tomcat8","type":"text","marks":[{"type":"code"}]},{"text":" folder to set logging to ","type":"text"},{"text":"ALL","type":"text","marks":[{"type":"code"}]},{"text":" and uncomment realm logging.","type":"text"}]},{"type":"paragraph","content":[{"text":"Edit the ","type":"text"},{"text":"logging.properties","type":"text","marks":[{"type":"code"}]},{"text":" file. Compare the original version to the edited version below to see the 3 places where you need to modify the Tomcat logging configurations:","type":"text"}]},{"type":"paragraph","content":[{"text":"Original Logging Configuration","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of the original logging configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"powershell"},"content":[{"text":"...\n5semarchy.org.apache.juli.AsyncFileHandler.level = FINE\n...\norg.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = INFO\n...\n# From Semarchy\n# enable realm logging\n#org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL\n#org.apache.catalina.realm.level = ALL\n#org.apache.catalina.realm.useParentHandlers = true\n#org.apache.catalina.authenticator.level = ALL\n#org.apache.catalina.authenticator.useParentHandlers = true","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Edited Logging Configuration","type":"text","marks":[{"type":"em"}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example of the edited logging configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"powershell"},"content":[{"text":"...\n5semarchy.org.apache.juli.AsyncFileHandler.level = ALL\n...\norg.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL\n...\n# From Semarchy\n# enable realm logging\norg.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/semarchy].level = ALL\norg.apache.catalina.realm.level = ALL\norg.apache.catalina.realm.useParentHandlers = true\norg.apache.catalina.authenticator.level = ALL\norg.apache.catalina.authenticator.useParentHandlers = true\ncom.semarchy.tool.jee.tomcat.level = ALL","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Once logging is correctly configured, you need to restart Tomcat for the changes to take effect. Find the newly created logging file called ","type":"text"},{"text":"realm-authenticator.log","type":"text","marks":[{"type":"code"}]},{"text":" in the ","type":"text"},{"text":"/var/log/tomcat8","type":"text","marks":[{"type":"code"}]},{"text":" folder (assuming you are on Linux). Catalina logs and localhost logs might contain relevant messages with detailed error.","type":"text"}]},{"type":"paragraph","content":[{"text":"Extra resources: The ","type":"text"},{"text":"log4j levels documentation","type":"text","marks":[{"type":"link","attrs":{"href":"http://org.apache.log4j.Level levels."}}]},{"text":" and a more ","type":"text"},{"text":"user-friendly version","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.tutorialspoint.com/log4j/log4j_logging_levels.htm"}}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"LDAP client tools: ...","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Sample configuration files","type":"text"}]},{"type":"paragraph","content":[{"text":"aaa, bbb","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Related Documentation","type":"text"}]},{"type":"paragraph","content":[{"text":"Standard product documentation in the Installation Guide is here: ","type":"text"},{"text":"https://www.semarchy.com/doc/semarchy-xdm/semng.html#delegating-authentication-and-authorization-in-tomcat","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.semarchy.com/doc/semarchy-xdm/semng.html#delegating-authentication-and-authorization-in-tomcat"}}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related articles","type":"text"}]},{"type":"paragraph","content":[{"type":"placeholder","attrs":{"text":"The content by label feature displays related articles automatically, based on labels you choose. To edit options for this feature, select the placeholder below and tap the pencil icon."}}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"contentbylabel","parameters":{"macroParams":{"showLabels":{"value":"false"},"max":{"value":"5"},"spaces":{"value":"com.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier@140ea"},"showSpace":{"value":"false"},"sort":{"value":"modified"},"type":{"value":"page"},"reverse":{"value":"true"},"labels":{"value":"sso ldap"},"cql":{"value":"label in ( \"ldap\" , \"sso\" ) and type = \"page\" and space = \"SKB\""}},"macroMetadata":{"macroId":{"value":"fb449c1e-0192-4f49-9bae-f5fe5c5d6589"},"schemaVersion":{"value":"4"},"title":"Filter by label (Content by label)"}}}},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"details","parameters":{"macroParams":{"hidden":{"value":"true"}},"macroMetadata":{"macroId":{"value":"5dcbc6bc-768b-4f7c-b748-4824f89d4c19"},"schemaVersion":{"value":"1"},"title":"Page Properties"}}},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"table","attrs":{"layout":"default"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[515.0]},"content":[{"type":"paragraph","content":[{"text":"Related issues","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[244.0]},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}

Browser not supported