Implementing SSL or TLS to LDAP server in Harvest
Article ID: 55323
Updated On:
Products
Issue/Introduction
Description:
Harvest servers can be configured to authenticate user credentials via internal or openLDAP authentication.
If openLDAP authentication is used, all communications between Harvest and the openLDAP server occur in clear text by default.
To increase security, this traffic can be encrypted by using a Secure Sockets Layer (SSL) tunnel or Transport Layer Security (TLS).
This article describes how to configure Harvest servers to use either of these protocols when communicating with an openLDAP (Lightweight Directory Access Protocol) server.
Environment
Harvest Software Change Manager v13.x, 14.x and up
Resolution
First Steps
If this is a new Harvest installation, or you are converting from internal authentication to openLDAP, the first step should be to get openLDAP authentication working correctly with no security enabled. This article assumes that you have already configured Harvest to connect to your openLDAP server over a non-secure connection and are ready to configure security for this connection.
SSL or TLS?
Once you are able to log in successfully to Harvest over openLDAP, you will need to decide which encryption method to use between Harvest and your openLDAP server.
Most current LDAP servers are version 3 compliant (LDAPv3), which supports TLS. This means that your LDAP server can recognize a startTLS command and establish TLS on the connection without the benefit of an SSL connection or an initial Bind command.
Some Microsoft Windows Server, however, uses Active Directory Service Interfaces (ADSI) version 2.5, which only supports SSL (also known as LDAPS, LDAPv2, or LDAP over SSL). In this older method, an SSL connection on TCP port 636 (by default) must first be established before a TLS handshake occurs because the startTLS command is not recognized. LDAPv2 was never standardized and has been deprecated as of 2003. So, if your LDAP server supports startTLS, you should use TLS instead of SSL.
How SSL & TLS work with LDAP
A client (Harvest) starts an LDAP session by connecting to an LDAP server (by default on TCP port 389 for unsecured and TLS connections or by default on TCP port 636 for SSL connections).
The client then sends operation requests to the server, which sends responses in turn. With some exceptions, the client need not wait for a response before sending the next request, and the server may send the responses in any order.
Create TLS Certificate and Key files
Regardless of whether you have opted for TLS or SSL, you will need a Trusted Certificate File, a Client Certificate File, and a Client Certificate Private Key File. This is because SSL actually implements TLS - it's just that it lacks the startTLS command, only invoking it after performing an initial Bind. You will also require a certificate for your LDAP server. Your LDAP server may already have a certificate issued by a 3rd party CA (Certificate Authority) such as Verisign, or you may need to generate your own internal certificate for use within your domain. Generating an LDAP server certificate is beyond the scope of this article. If you need to generate your own new certificate files and client private key file, you will need Domain Administrator (Windows) or root (UNIX/LINUX) privileges. Step-by-step instructions for creating the three client (Harvest) side files can be found in "Configure Broker and Server on UNIX, Linux, and zLinux" Look for the section titled "Securing Communication to the LDAP Server"
Harvest will use the Trusted Certificate File to determine whether the LDAP server should be trusted. This file must be in PEM format and contain a list of Trusted Certificate Authorities, one of which must match the Authority that granted the certificate for the LDAP server.
The Client Certificate File is presented by Harvest to the LDAP server for authentication.
The Client Certificate Private Key File is used to verify the authenticity of the client (Harvest) requesting services from the LDAP server. This file must not be encrypted.
Configure Harvest for SSL or TLS
If you have successfully implemented openLDAP with Harvest over a non-secure connection, then you have already set all the parameters necessary to successfully query your LDAP server. To implement TLS or SSL secure communications between the Harvest server and LDAP server, edit the %HARVESTHOME%/Hserver.arg file (for Windows) or the $HARVESTHOME/HServer.arg file (for UNIX/LINUX) and add these parameters:
-ldapmode=tls
-or-
-ldapmode=ssl
-tlstrcertfile=[Full path and filename of the Trusted Certificate File]
-tlscertfile=[Full path and filename of the Client Certificate File]
-tlskeyfile=[Full path and filename of the Client Certificate Private Key File]
You must restart Harvest brokers and servers for the changes to take effect.
Additional Information
For more information on how to enable and configure openLDAP authentication, refer to the chapter Configure Broker and Server on UNIX, Linux, and Linux in the documentation and technical article Converting Harvest from Internal to LDAP authentication.
Feedback
