Converting Harvest from Internal to LDAP 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) and allow users to log in to Harvest.

After installing Harvest, it is possible to change the authentication method from internal to external or vice versa. This article will 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 documentation 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, all versions and platforms

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 hostname or fully qualified domain name (FQDN) of your LDAP Server.
• Ldapport. The port number that the LDAP server is using to listen for incoming requests for authentication.
• Ldapbinddn: The LDAP Distinguished Name of the userid that Harvest will use to connect to the LDAP server
• Ldapbindpw: The password for the userid that Harvest will use to connect to the LDAP server.
• Ldapbasedn: The place inside the LDAP directory where Harvest will begin its search for users. Often, this is an Organizational Unit (OU).
• Ldapfilter: When searching for a user in the LDAP directory, this setting specifies which directory entries to consider and which to ignore.
• Ldapattrusrname: The name of the attribute in the LDAP directory 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 use an LDAP browser such as the SysInternals AD Explorer. This can confirm that you can connect, log in, and search for users.

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 your configuration settings are correct, you can use this working set of parameters to plug into Harvest's configuration files.

Here's an example of an hauthtst command line. It must be entered as one continuous line, a space between each option, with no CR/LFs 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. The command output will go to hauthtst.log in the current directory.

Hauthtst <example userid> -o hauthtst.log
-authmode=openldap
-ldapmode=none
-ldapserver="<ldap server name>"
-ldapport=<ldap port number>
-ldapbinddn="<distinguished name of user to connect to LDAP>"
-ldapbindpw="<password of user to connect to LDAP>"
-ldapfilter="<example filter>"
-ldapattrusrname="<LDAP attribute containing userid>"
-ldapbasedn="<LDAP base distinguished name>"

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

Note: You will see a new option listed here, "-ldapmode".  This option tells Harvest how to communicate with the LDAP server.  The options are

• "-ldapmode=none" indicates that no encryption should be used in communication. When this mode is selected, your "-ldapport=" option would normally be set to 389, but check with your LDAP administrator to be sure.  Important! If you specify none (no encryption), user credentials and all other information exchanged between Harvest and the LDAP server is transmitted in clear-text mode.
  
  
• "-ldapmode=ssl" specifies that the Secure Socket Layer will be used for the communication protocol
  
  
• "-ldapmode=tls" specifies Transport Layer Security will be used for the communication protocol. Specify TLS only if your LDAP server supports StartTLS.  When using this mode of communication, you will need to have a CA certificate file, a certificate file, and a key file.  These will normally be provided by your LDAP administrator.

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

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

HARTABLEINFO.CASESENSLOGIN=[Y/N]

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.

These are the only two LDAP-related parameters to be 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:

-mixedauthmode=1
-authmode=openldap
-ldapmode=none
-ldapserver="<ldap server name>"
-ldapport=<ldap port number>
-ldapbinddn="<distinguished name of user to connect to LDAP>"
-ldapbindpw="<password of user to connect to LDAP>"
-ldapfilter="<example filter>"
-ldapattrusrname="<LDAP attribute containing userid>"
-ldapbasedn="<LDAP base distinguished name>"

Note: we will add one more option at this point, "-mixedauthmode=".  This setting will let Harvest know whether all users will be authenticated through LDAP (-mixedauthmode=0), or whether some are authenticated through LDAP while others are authenticated by Harvest using a password stored in the Harvest database (-mixedauthmode=1).  If you specify "-mixedauthmode=1", there is a setting for each user called "External".  If this checkbox is checked, the user will be authenticated through LDAP, and if unchecked, they will be authenticated through Harvest.

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