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.

Table of Contents Important directory connection concepts Directory browsing software: JXplorer and Apache Directory Studio LDAP directory tree Distinguished Names Troubleshooting for connecting the geoportal with the directory server Incorrect Distinguished Names Problems with the searchDIT Issues with the ldapServiceAccount parameter Configure the geoportal for Windows Active Directory, Oracle Internet Directory, or IBM Tivoli Directory Server ldapAdapter section configuration for Windows Active Directory ldapAdapter section configuration for Oracle Internet Directory ldapAdapter section configuration for IBM Trivoli

Important directory connection concepts

Listed below are important concepts to understand to configure your geoportal LDAP authentication configuration to your directory server.

Directory browsing software: JXplorer and Apache Directory Studio

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.

LDAP directory tree

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.

Distinguished Names

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.

Troubleshooting for connecting the geoportal with the directory server

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.

Incorrect Distinguished Names

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.

1. Open your gpt.xml file.
2. Find the ldapAdapter section
3. 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

Caution: if you change any of these values in your gpt.xml file, you will have to save the file and restart your geoportal web application for the changes to take place.

Problems with the searchDIT

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:

1. Open your directory browsing software, connect to your LDAP configuration, and note the location of your users in the DIT.
2. Now note the location of the geoportal groups.
3. 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.

Issues with the ldapServiceAccount parameter

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.

Verify that your securityPrincipal is set to point to the DN of the user who has privileges to connect to the LDAP, and that your catalogAdminDN is configured to the DN of a Geoportal Administrator user. The graphic below shows that these are two different users, and where they would be in our example DIT:

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.

1. Navigate to the \\geoportal\WEB-INF\classes\gpt\config folder and open the gpt.xml file in a text editor, such as Notepad.
2. In the gpt.xml file, scroll down to the section where the LDAP connection information is defined, beginning with the ldapAdapter tag.
3. 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.

ldapAdapter section configuration for Windows Active Directory

If the directory server software is Windows Active Directory, do the following.

1. In displayNameAttribute in the users tag, replace cn with sAMAccountName.
2. In the usernameSearchPattern attribute, change (&(objectclass=person)(cn={0})) to read (&(objectclass=person)(sAMAccountName={0})).
3. In the userAttributeMap\attribute element, find the key for username. Change the ldapName for this from uid to sAMAccountName.
4. In the groups element memberAttribute, change uniquemember to member.
5. In memberSearchPattern change (&(objectclass=groupOfUniqueNames)(uniquemember={0})) to (&(objectclass=group)(member:1.2.840.113556.1.4.1941:={0})).
6. 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.

ldapAdapter section configuration for Oracle Internet Directory

If the directory server software is Oracle Internet Directory, do the following.

1. In displayNameAttribute in the users tag, replace cn with uid.
2. In the usernameSearchPattern attribute, change (&(objectclass=person)(cn={0})) to read (&(objectclass=person)(uid={0})).
3. In the userAttributeMap\attribute element, find the key for username. Verify that the ldapName for this is uid.
4. In the groups element, find the DynamicMemberOfGroupsAttribute attribute, and enter controlid=2.16.840.1.113894.1.8.3.
5. Example of the configured file:

ldapAdapter section configuration for IBM Trivoli

1. If the directory server software is IBM Trivoli, do the following:
2. In the dynamicMemberOfGroupsAttribute groups tag, enter ibm-allgroups.
3. In the dynamicMembersAttribute, enter ibm-allmembers.
4. In the memberAttribute, change uniquemember to member.
5. In the memberSearchPattern, change &(objectclass=groupOfNames)(uniquemember={0})) to (&(objectclass=groupOfNames)(member={0})).
6. Example of the configured file: