Connecting to a User Directory
The Geoportal Server supports user management through integration with various LDAP providers. Instructions in the installation guide use Apache Directory Server for the example directory integration. Your organization may use different directory server software, and this topic will tell you what you need to do to connect the geoportal to those different systems. This topic will also describe important directory concepts, and troubleshooting steps if it seems that the geoportal directory integration is having problems.
Listed below are important concepts to understand to configure your geoportal LDAP authentication configuration to your directory server.
JXplorer or Apache Directory Studio are freely downloadable tools for browsing a directory server. They are not ESRI products, and the Geoportal Server is not dependent on them. However, because a directory server client is necessary for these troubleshooting steps, the instructions below assume you have installed and configured these or another directory server browsing tool. The examples below reference JXplorer.
The LDAP directory is set up in a tree structure called the Directory Information Tree (DIT). The tree can have many branches, with users and groups defined as sub-branches. Below is a simple tree, with users located in the "system\users" branch, and groups located in the "system\groups" branch.
In most organizations, the DIT is more complex. There may be groups for different regions, authority levels, project teams, and more. It is strongly recommended that the group structure created maps directly to the pre-defined geoportal roles. If this is not possible, you will need to coordinate with your LDAP system administrator to decide what the best possible mapping is of your existing groups to the geoportal roles.
Every user or group in the DIT has a unique identifier: its Distinguished Name (DN). An example of the DN for the gptadmin user in the screenshot above is cn=gptadmin,ou=users,ou=system. The DN is made up of a unique identifier (the cn part), and then the path that allows the geoportal to navigate to that user or group within the DIT structure (the branches of the DIT, which are the ou parts). You can use your directory browsing software to copy the DN for a user or group in the DIT and populate the gpt.xml file with correct values. Connect to your LDAP with the directory browsing software, and then highlight the user or group whose DN you need with your mouse. If you are using JXplorer, you can right click, and select the Copy DN option. You can now paste this value into your gpt.xml file.
Note: This section assumes an understanding of LDAP concepts outlined above in Important directory connection concepts
When problems exist with LDAP information being passed into the geoportal, in most cases one of the following is the cause. Troubleshooting steps for these issues are described below.
In this case, the Distinguished Name (DN) for one or more of the parameters in the roles, users, or groups section of the gpt.xml file is incorrect. Below are steps to address this.
- Open your gpt.xml file.
- Find the ldapAdapter section
- Check the following values, and verify that the correct DN is associated with each parameter. Remember that you can get the exact DN of a user or group by connecting to the directory tree with directory browsing software and copying the DN. The examples below map to the example directory tree shown in the Important directory connections concepts section above:
| gpt.xml parameter | description | example |
|---|---|---|
| ldapConnectionProperties\ldapServiceAccount\catalogAdminDN (Note, as of version 1.2, this parameter is no longer needed and won't be present in the gpt.xml file) | This is the DN of a member in the geoportal administrators group | cn=gptadmin,ou=users,ou=system |
| roles\role\ groupDN | Three such settings exist and will point to the DN's of the three geoportal role groups: Geoportal Registered Users, Publishers, and Administrators. | cn=gpt_registeredUsers,ou=groups,ou=system |
| users\newUserDNPattern | This is the DN path indicating where to insert a user entry when a new user is created in the geoportal registration page. | cn={0},ou=users,ou=system |
| users\searchDIT | This is the DN path indicating how to navigate through the DIT to find users. | ou=users,ou=system |
| groups\searchDIT | This is the DN path indicating how to navigate through the DIT to find the geoportal role groups | ou=groups,ou=system |
If the users branch of the LDAP Directory Information Tree (DIT) is not accessible to the geoportal, then the users mapped to the groups cannot be located. This is a matter of having the correct values in the searchDIT parameters. The geoportal may be able to find your groups, but it also needs to be able to find the users assigned to those groups. Below are steps to address this:
- Open your directory browsing software, connect to your LDAP configuration, and note the location of your users in the DIT.
- Now note the location of the geoportal groups.
- Doublecheck the parameters for the searchDIT for the users and groups sections in the gpt.xml file. Make sure you have indicated correctly how to navigate the DIT to get to both the users and groups branches.
The gpt.xml file has a section called ldapConnectionProperties. Within that section, there is a ldapServiceAccount parameter where a securityPrincipal user is defined, and if your geoportal is a version before 1.2, a catalogAdminDN user is defined (at version 1.2, the catalogAdminDN is no longer needed and is therefore not defined in the gpt.xml file). These two users have different functions, and do not have to be the same user.
- The securityPrincipal user is for connecting to the LDAP system, and need not be - and usually is not - a user from the geoportal administrators group.
- The catalogAdminDN is for the geoportal catalog administration user, and must be a user from the geoportal administrators group.
Configure the geoportal for Windows Active Directory, Oracle Internet Directory, or IBM Tivoli Directory Server
By default, the geoportal gpt.xml user directory integration is configured for Apache Directory Server. This section provides instructions for configuring the geoportal to integrate with Windows Active Directory, Oracle Internet Directory, or IBM Tivoli Directory Server. Use these steps and examples as a starting point; it's likely that your organization's configuration may vary from the examples provided. Steps are provided below. Note: Below there are example screenshots of the configurations described. In these examples, the Distinguished Names (DN) are placeholders representing a sample organization's LDAP structure. Elements that may need to be changed to support the specific directory server software are shown in yellow.
- Navigate to the \\geoportal\WEB-INF\classes\gpt\config folder and open the gpt.xml file in a text editor, such as Notepad.
- In the gpt.xml file, scroll down to the section where the LDAP connection information is defined, beginning with the ldapAdapter tag.
- Configure the LDAP definition section as instructed in the relevant section below (Windows Active Directory, Oracle Internet Directory, or IBM Tivoli) - when finished, save the gpt.xml file, and restart the geoportal web application for the changes to take effect.
If the directory server software is Windows Active Directory, do the following.
- In displayNameAttribute in the users tag, replace cn with sAMAccountName.
- In the usernameSearchPattern attribute, change (&(objectclass=person)(cn={0})) to read (&(objectclass=person)(sAMAccountName={0})).
- In the userAttributeMap\attribute element, find the key for username. Change the ldapName for this from uid to sAMAccountName.
- In the groups element memberAttribute, change uniquemember to member.
- In memberSearchPattern change (&(objectclass=groupOfUniqueNames)(uniquemember={0})) to (&(objectclass=group)(member:1.2.840.113556.1.4.1941:={0})).
- Example of the configured file:
Note: if you would like to allow for user registration/password change in Geoportal for Active Directory, the Application Server (e.g. Tomcat) need to have the AD server certificate in its JVM, the steps would involve exporting the Active Directory SSL certificate and import it into the JVM trusted certificate store where the Application Server is running.
If the directory server software is Oracle Internet Directory, do the following.
- In displayNameAttribute in the users tag, replace cn with uid.
- In the usernameSearchPattern attribute, change (&(objectclass=person)(cn={0})) to read (&(objectclass=person)(uid={0})).
- In the userAttributeMap\attribute element, find the key for username. Verify that the ldapName for this is uid.
- In the groups element, find the DynamicMemberOfGroupsAttribute attribute, and enter controlid=2.16.840.1.113894.1.8.3.
- Example of the configured file:
- If the directory server software is IBM Trivoli, do the following:
- In the dynamicMemberOfGroupsAttribute groups tag, enter ibm-allgroups.
- In the dynamicMembersAttribute, enter ibm-allmembers.
- In the memberAttribute, change uniquemember to member.
- In the memberSearchPattern, change &(objectclass=groupOfNames)(uniquemember={0})) to (&(objectclass=groupOfNames)(member={0})).
- Example of the configured file:
