How to convert Harvest servers to use external (openldap) authentication where Harvest was installed with internal authentication

Products

• CA Harvest Software Change Manager - OpenMake Meister

Issue/Introduction

During Harvest installation, you must specify the method to be used to authenticate users wishing to login to Harvest.

You may select internal authentication (the default), which relies on Harvest itself to authenticate users, or you may specify external authentication.

External authentication relies on a Lightweight Directory Access Protocol (LDAP) v3-compliant LDAP server, such as Microsoft Active Directory, IBM Tivoli, or Novell eDirectory, to validate the credentials (user names and passwords) allowing users to login to Harvest.

After installing Harvest, it is possible to change the authentication method from internal to external, or vice-versa. The purpose of this article is to walk you through an example scenario in which a Harvest server is converted from internal (Harvest) to external (openldap) authentication.

This is only a hypothetical situation designed to provide insight into specific aspects of the conversion process. It is not an exhaustive study of all platforms, options, or scenarios. Configuration of Harvest multi-user remote agents and Harweb are not discussed. Your situation may differ, and you are encouraged to consult the Harvest r7.1 Administrator's Guide, Chapter 2, for a complete discussion of authentication.

With that said, let's take a look at the basic steps required to implement external LDAP authentication for Harvest servers.

Environment

CA Harvest Software Change Manager

Resolution

For this demonstration case, we will be using Microsoft's Active Directory LDAP Server. We will not implement secure communications between the LDAP Server and Harvest. A discussion of secure communications is beyond the scope of this document.

Step 1: Obtain LDAP configuration information specific to your domain.

Contact your network domain administrator or Active Directory administrator to obtain some basic information about your local configuration. You will need to know:

1. Domain name of your LDAP Server.
   
   Note: Be aware that Harvest cannot communicate with an LDAP Server that is in a different domain, even if that domain is trusted.

• Ldapserver. The name of your LDAP Server.
• Ldapbasedn. Often an Organizational Unit (OU).
• Ldapbinddn. LDAP Bind Distinguished Name.
• Ldapbindpw. LDAP Bind Password.
• Ldapport. For unsecured connections such as we are setting up here, the default port is 389.
• Ldapfilter. Used for locating user entries.
• Ldapattrusrname. LDAP attribute corresponding to the Harvest Username.

To verify that you have all the information you need to access entries in the LDAP database, you may want to download a handy 3rd party tool which, as of this writing, is available for free on the internet. LDAP Browser allows you to connect to an LDAP Server and examine its structure. It is available at
http://www.ldapbrowser.com/download/index.php

Step 2: Run hauthtst

Once you have obtained your domain's LDAP configuration information, port setting, and server location, the next step is to test your LDAP connection outside of Harvest.

The purpose of hauthtst is to test the communications channel between Harvest and your LDAP server without having to reconfigure Harvest. This simplifies any troubleshooting you may need to do. Once you are satisfied that hauthtst is configured correctly, you can use this working set of parameters to plug in to Harvest's configuration files.

Here's an example hauthtst command line. It must be entered as one continuous line with no cr/lf's or other line breaks. Do not use word wrap if you save it in Notepad, though you can copy and paste it into a command prompt window. Any parameter that contains spaces must be enclosed in quotes. For readability, I've listed one parameter per line, but at a DOS command prompt it must be entered as one continuous string. Command output will go to hauthtst.log in the current directory.

Hauthtst myuser -o hauthtst.log
-authmode=openldap
-ldapmode=none
-ldapserver="ldapservername"
-ldapport=389
-ldapbinddn="cn=myuser,cn=users,dc=harvestsupport"
-ldapbindpw="myuserpwd"
-ldapfilter="(&(objectClass=*))"
-ldapattrusrname="sAMAccountName"
-ldapbasedn="dc=harvestsupport"

If necessary, tracing can be turned on by adding
-ldapdebuglevel=1

Step 3: Configure Harvest brokers and servers to use external LDAP authentication.

Harvest brokers and the servers they connect to must use the same authentication method (internal or openldap). Harvest agents are configured separately and do not depend on the authentication method chosen for brokers and servers. Configuration of Harvest agents and Harweb is not covered in this document.

To configure your brokers and servers, there is one parameter in the Harvest database you must check.

HARTABLEINFO.CASESENSLOGIN=[Y/N]

The value of this parameter determines whether userids are treated as case sensitive or not. The default value is "Y". If your LDAP server validates userids with case sensitivity you must set this parameter to "Y".

To activate and configure LDAP for Harvest brokers, first make a backup copy of your current %HARVESTHOME%/HBroker.arg file, which is located on your Harvest server computer. This file only accepts two LDAP related parameters.

-authmode=openldap

The default value for this parameter is "internal". It is possible that this parameter does not exist in your current HBroker.arg file, since internal authorization is assumed. To change to LDAP, you must add this parameter (if necessary) and set its value to "openldap".

-authsynchinterval=[dd:hh:mm:ss]

This parameter specifies the amount of time between background synchronizations of the user data in the LDAP server and the Harvest database. The default is 1 (one day). This parameter is optional and will default to once per day if not specified.

There are no other LDAP related parameters you can set in HBroker.arg. All other LDAP parameters must be defined in the file HServer.arg. In fact, if you make a mistake and put additional LDAP parameters in your HBroker.arg file, you will receive error messages indicating that you have invalid parameters, and your broker will not start.

Most of the configuration necessary to implement LDAP authentication in Harvest occurs in the %HARVESTHOME%/HServer.arg file located on your Harvest server computer. It is in this file that you will set the values for LDAP authentication that you obtained in Step 1 and verified with the Hauthtst utility in Step 2. Be sure to make a backup copy of this file before you start editing it.

Using the values we confirmed with our example Hauthtst command, above, you would add the following entries to HServer.arg:

-authmode=openldap
-ldapmode=none
-ldapserver="ldapservername"
-ldapport=389
-ldapbinddn="cn=myuser,cn=users,dc=harvestsupport"
-ldapbindpw="myuserpwd"
-ldapfilter="(&(objectClass=*))"
-ldapattrusrname="sAMAccountName"
-ldapbasedn="dc=harvestsupport"

To activate LDAP authentication for Harvest, simply stop and restart the Harvest broker/servers with these new argument files in place.