/geoportal-server

Configure a Directory Server for the Geoportal

zguo edited this page Apr 12, 2014 · 8 revisions
Clone this wiki locally

For a complete feature-rich geoportal, the authentication mechanism must rely on LDAP communication. If you already have an existing Directory Server setup in your organization, you may use it for geoportal purposes with minimal configuration customizations. For users without a pre-existing Directory Server, Section below will help you through the steps of setting up an open source Directory Server for the geoportal. If you have an existing Directory server accessible via LDAP, skip section "Install a New Directory Server and Client" and proceed directly to "Adapt an Existing Directory Server".

Install a New Directory Server and Client

1. Install Directory Server
There are many directory server software packages available. For the purposes of this installation guide we have selected Apache Directory Server. Apache Directory Server can be downloaded from: http://directory.apache.org. After the installation of your Directory Server is complete, make sure that the Directory Server is active, by checking whether its service is started.

  • Open Control Panel>Administrative Tools>Services
  • Highlight the service representing your Directory Server.
  • If its status is not "Started", click "Start".

2. Install Directory Server Client
There are also many directory server clients available for browsing your directory structure. For the purposes of this installation guide we have selected Apache Directory Studio, downloadable from http://directory.apache.org/studio/.

3. Define a Connection from the client to the server
The information in this section assumes you have installed Apache Directory Server and Apache Directory Studio. If you have a different combination of software, you can skip this step or use the information within it as a guide.

  • Launch Apache Directory Studio.
  • From the File menu, select "New…" and then "LDAP Connection".
  • On the Network Parameter screen, enter the following parameters:
    • Connection name: Can be any name. Here, input local.
    • Hostname: The machine name on which the LDAP server was installed, in your case, this computer so you can input localhost.
    • Port: The port number on which the LDAP server is running. For a default Apache Directory Server service, it will be 10389.
    • Encryption method: No encryption for this connection.
  • Now click the Check Network Parameter button. You should receive a message that the connection was successful. Click Next.
  • On the Authentication screen, enter the following parameters:
    • Authentication Method: Choose Simple Authentication.
    • Bind DN or user: enter the distinguished name (DN) of the default admin user. For Apache Directory Server, the default DN will be uid=admin,ou=system.
    • Bind password: The password to the LDAP server for the admin user. For Apache Directory Server, the default password will be secret.
  • Click the Check Authentication button. You should receive a message that the authentication was successful. Click Finish.
  • In the left-hand pane of the window, you should see a tree structure with DIT as the top node. You are now connected to the LDAP server.
  • An initial structure of entries was created when you installed Apache Directory Server. If you expand the DIT node, and then the ou=system node, you will see nodes with groups and users beneath it.
4. Create an initial user
In this step you will create a user entry, to which you will later grant geoportal administrator privileges.
  • In the LDAP Browser window in Apache Directory Studio, right-click the users node and select New, and then New Entry from the shortcut menu.
  • Select Create entry from scratch from the Entry Creation Method dialog box that appears. Click Next.
  • In the Object Classes dialog box, choose object classes from the object class list. The following four classes need to be chosen for this node:
    • inetOrgPerson
    • organizationalPerson
    • person
    • top
  • If more than the four classes listed above are listed, remove the extras by selecting them in the right-hand panel Selected object classes and clicking the Remove button. Click Next.
  • In the second text box, labeled RDN, select "cn" in the left box and type "gptadmin" in the right box to make cn= gptadmin. This sets the user's name as gptadmin. Click Next.
  • Now you will see the Attributes dialog for the new user. Double click in the Value column next to the sn attribute. This would be the last name of your user, but for this example, use the same name, gptadmin.
  • Now you will add additional information about your user, using the New Attribute functionality. Here, we will add first the email, then the password, and finally the userid attributes.
    • For email:
      • Put your cursor in the empty cell in the Attribute Description column beneath sn, and rightclick. Select New Attribute from the right menu.
      • Select mail from the Attribute type drop down, and click Next.
      • On the resulting Options screen, accept the defaults and click Finish.
      • Doubleclick the mail attribute in your Attribute Description column and enter a fictional email address for gptadmin.
      • After entering the email address, click off of the Value column to preserve the entered information.
    • For the password:
      • Put your cursor in the empty cell in the Attribute Description column beneath mail, and rightclick. Select New Attribute from the right menu.
      • Select userPassword from the Attribute type drop down, and click Next.
      • On the resulting Options screen, accept the defaults and click Finish.
      • Upon clicking Finish, the Password Editor dialog appears. Enter a password for your user, and leave the rest of the defaults. Click OK.
    • The uid should be the same as the user name used to create the entry, and the same as the cn attribute value listed in the table. This id is used to login to the geoportal interface.
      • Put your cursor in the empty cell in the Attribute Description column beneath userPassword, and rightclick. Select New Attribute from the right menu.
      • Select uid from the Attribute type drop down, and click Next.
      • On the resulting Options screen, accept the defaults and click Finish.
      • Doubleclick the userid attribute in your Attribute Description column and enter the same name you entered to create the user, e.g., gptadmin.
      • After entering the userid, click off of the Value column to preserve the entered information.
  • After adding the new attributes, click Finish to close the New Entry dialog. The new gptadmin user should appear as a new node under the users node in the directory structure.
  • You can repeat the above steps to create test users for the remaining geoportal roles. We suggest using the following user names:
    • gptpublisher
    • gptuser

Your Directory Server is now ready to be populated with additional geoportal-specific entries. Follow the steps in Section 3.2 to finish configuring your Directory Server for the geoportal.

Adapt an Existing Directory Server

The geoportal relies on user roles in order to grant various user and functionality privileges. The three pre-defined geoportal roles are:

  • Administrator
  • Publisher
  • Registered User
With LDAP authentication, the definition of the geoportal roles is achieved by creating Directory Server "group" entries. A group entry is defined as an entry that has an object class of "groupOfUniqueNames", thereby allowing it to have member (person) entries.

1. Create groups for the geoportal roles

The group structure in your Directory Server does not have to adhere to any particular schema. However it is strongly recommended that you adhere to a group structure which maps directly to the pre-defined geoportal roles.

If you are working with a newly installed Directory Server, this is fairly straightforward to create, and instructions are provided in this section.

If you are working with an existing Directory Server, you can either create a new set of groups specifically for the geoportal, or decide what the best possible mapping is of your existing groups to the new geoportal roles. This needs to be done in such a way that it does not disrupt your existing applications' authentication mechanisms, yet can be adapted to the geoportal requirements.

The steps in this section assume the following:
a) You are using Apache Directory Studio as your Directory Server client browser.
b) You will be creating groups that directly map to the geoportal roles.
c) You have an organizational unit in your directory structure called "groups". If you have another organizational unit, substitute your organizational unit’s name for the word "groups" in the steps below.

  • Open Apache Directory Studio if it isn't already open and connect to your directory server.
  • Right-click the groups node and select New, and then New Entry from the shortcut menu.
  • Select Create entry from scratch from the Entry Creation Method dialog box that appears. Click Next.
  • In the Object Classes dialog box, choose object classes from the object class list. The following two classes need to be chosen for this node:
    • groupOfUniqueNames
    • top
  • If more than the two classes listed above are present, remove the extra ones by selecting them in the right-hand panel Selected Classes and clicking the Remove button. Click Next.
  • On the next screen, go to the second text box, which is labeled RDN. Select "cn" in the left box and enter a group name of gpt_administrators. This sets the new group's name as gpt_administrators. This is the group to which you'll later assign geoportal administration privileges.
  • Click Next.
  • The Attribute dialog box appears where the uniqueMember attribute must be specified.
  • Since uniqueMember DN's are not trivial, temporarily enter placeholder information for the value of uniqueMember. Even though you are putting in placeholder information, it still has to conform to LDAP standards. Enter cn=abc.
  • Click Finish to create the group. The new group gpt_administrators should appear as an entry under groups in the directory structure.
  • Create two more new groups using the same steps as above. Use the following user group names, and remember to assign placeholder uniqueMember values to each. Note that in production, you can map geoportal functionality to existing groups in your organizational structure.
    • For geoportal publisher users, create a group called gpt_publishers
    • For geoportal registered users, create a group called gpt_registeredUsers
  • Now you will add the gptadmin user to the gpt_administrators group. Navigate to the Users branch, and right-click on the gptadmin user. Select Copy Entry / DN from the shortcut menu.
  • Go back to the groups branch and click the gpt_administrators group.
  • In the Attribute panel on the right-hand side, doubleclick inside the Value column for the uniqueMember attribute that has the placeholder cn=abc value.
  • Press Ctrl+V on your keyboard to paste the copied DN from the clipboard into this value field. Now, gptadmin is part of the gpt_administrators group.
  • Repeat these steps to associate your gptpublisher and gptuser users to the gpt_publishers, and gpt_registeredUsers groups respectively, using the same steps.