Connecting to a User Directory

Connecting the Geoportal to a user directory tree

Geoportal extension 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 section will also describe important directory concepts, and troubleshooting steps if it seems that the geoportal directory integration is having problems.

Important directory connections concepts

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

  1. 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 extension 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.

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

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

NoteNote:

This article assumes an understanding of LDAP concepts outlined above in Important LDAP 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.

  1. Incorrect Distinguished Names
  2. Problems with the searchDIT
  3. Issues with the <ldapServiceAccount> parameter

Troubleshooting 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 conceptssection above:

    gpt.xml parameter

    description

    example

    ldapConnectionProperties\ldapServiceAccount\catalogAdminDN

    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

CautionCaution:

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

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

Troubleshooting issues with the <ldapServiceAccount> parameter

The gpt.xml file has a section called <ldapConnectionProperties>. Within that section, there is a <ldapServiceAccount> parameter where two users are defined. The two users are the securityPrincipal user and the catalogAdminDN user. 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 extension to Windows Active Directory, Oracle Internet Directory, or IBM Tivoli Directory Server

By default, the Geoportal extension 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.

NoteNote:

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 Geoportal extension installation guide, adding the relevant entries for the LDAP connection, roles, users, and groups. Save the file.
  4. If the directory server software is Windows Active Directory, do the following. If not, proceed to Step 5 or 6:
    • 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:
    • Proceed to Step 7.
  5. If the directory server software is Oracle Internet Directory, do the following. If not, proceed to Step 6:
    • 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:
    • Proceed to Step 7.
  6. 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:
    • Proceed to Step 7.
  7. Save the gpt.xml file, and restart the Geoportal Web application for the changes to take effect.


Copyright © 1995-2012 Esri. All rights reserved.
8/6/2012