How do you implement SSL or TLS secure communications between Harvest and an openLDAP server?

Document ID : KB000055323
Last Modified Date : 14/02/2018
Show Technical Document Details


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 occurs in clear text by default.

To increase security, this traffic can be encrypted by using a Secure Socke ts Layer (SSL) tunnel, or the newer 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.

For more information on how to enable and configure openLDAP authentication, refer to the Harvest r7.1 Administrator's Guide, Chapter 2, and TEC428799 How to convert Harvest from Internal to openLDAP authentication, a technical article available on SupportConnect.

Microsoft Knowledgebase article 308149 PRB: Authentication Fails When You Log On As Current User by Using ADSI over SSL


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.


Once you are able to successfully login 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 suppor ts TLS. This means that your LDAP server is able to recognize a startTLS command and establish TLS on the connection without benefit of an SSL connection or an initial Bind command.

Microsoft's Windows 2000 Server, however, uses Active Directory Service Interfaces (ADSI) version 2.5, which only suppor ts 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 suppor ts startTLS, you should use TLS instead of SSL.

How SSL & TLS work with LDAP

A client (Harvest) star ts 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 reques ts to the server, and the server 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.

The client gives each request a positive Message ID, and the server response has the same Message ID. The response includes a numeric result code, which indicates a success, an error condition, or some special case.

The client (Harvest) may request the following operations of an LDAP server:

  • StartTLS - protect the connection with TLS (LDAPv3 only)
  • Bind - authenticate and specify the LDAP protocol version
  • Search - search for and/or retrieve directory entries
  • Compare - test if a named entry contains a given attribute value
  • Add a new entry
  • Delete an entry
  • Modify an entry
  • Modify Distinguished Name (DN) - move or rename an entry
  • Abandon - abort a previous request
  • Extended Operation - a generic operation used to define other operations
  • Unbind - close the connection (not the inverse of Bind)

StartTLS establishes Transport Layer Security (the descendant of SSL) on the connection. During TLS negotiation, the server sends i ts X.509 certificate to prove its identity. Harvest compares this with entries in the TLS_CACERT file to verify the identity of the LDAP server.

Harvest then sends i ts own certificate (the TLS_CERT file) to prove i ts identity. This client identity is used to determine whether Harvest is authorized to access the LDAP server on TLS connections.

The Bind operation authenticates Harvest to the server. Bind has to be the first command in a session in LDAPv2 (SSL), but is not required in LDAPv3 (TLS). Simple Bind can send the user's DN and password in clear text, so the connection should be protected with SSL or TLS. The LDAP server typically checks the password against the userPassword attribute in the named entry. Anonymous Bind (with an empty DN and password) resets the connection to the anonymous state. SASL (Simple Authentication and Security Layer) Bind provides authentication services through a wide range of mechanisms, e.g. Kerberos or the client certificate (the TLS_CERT file) sent with startTLS. Bind also sets the LDAP protocol version.

The LDAPv2 (SSL) Bind Problem

When using SSL with an LDAPv2 server (such as Microsoft Windows 2000 Server Active Directory Service Interfaces (ADSI) version 2.5), Harvest is authenticated to the LDAP server by a Simple Bind using the values specified in your Hserver.arg for ldapbinddn and ldapbindpw. Simple Binds convey a DN and password in clear text across the network. This is not a problem, since you have already established a secure SSL connection.

However, i f you provide an empty (NULL) DN and password over an SSL connection, ADSI interpre ts this as a request to perform an Anonymous Bind. This is very different.

An Anonymous Bind (NULL DN and password) over a non-secured connection resul ts in use of the security credentials of the logged-in user making the bind, so, everything should work. However, doing the same thing over an SSL connection resul ts in an Anonymous Bind being performed where the credentials used are truly anonymous (NULL DN and password). In this situation, you may find yourself unable to connect to or query the LDAP server because, by default, anonymous users are not given permission to view objects in the Active Directory. This problem is documented in Microsoft Knowledgebase article 308149.

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 3 rd 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 the Harvest r7.1 Administrator's Guide, Chapter 2, beginning on page 2-50.

The Trusted Certificate File will be used by Harvest to determine whether the LDAP server should be trusted or not. It contains a list of Trusted Certificate Authorities, one of which must match with the Authority, which granted the certificate for the LDAP server. This file must be in PEM format.

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:


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