Ephesoft provides integration with OpenLDAP and Active Directory. Ephesoft supports authenticating against these servers, and it also supports importing groups to use as Roles for Batch Classes and for setting user rights based on group membership.  However, all of the documentation provided describes connecting via LDAP, and not LDAPS (LDAP over SSL). This article describes the steps needed to connect to Active Directory using LDAPS instead of LDAP, so that your traffic to and from the Active Directory server is encrypted.

This article assumes that the Ephesoft server is currently set up and integrated with Active Directory using LDAP.  If not, the documentation to perform these steps may be found here:

• How to Configure Active Directory

Once this configuration is completed, the Ephesoft server will be accessing Active Directory via LDAP, but not LDAPS.  Although the configuration will allow you to specify “ldaps://” in the URL at this point, this configuration will not work. When the server tries to connect, the following error will be seen in the “catalina.out” log file:

javax.naming.CommunicationException: simple bind failed: [server name]:636 [Root exception is javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target]

In the “dcma” log files, you will also see errors about “Invalid Credentials”. This can be misleading, as the error is truly due to the connection failing, and not due to the login credentials themselves.

The basic issue is that the JDK does not have a certificate for the Active Directory server, so it has no way to validate the secure connection. Resolving this issue is straightforward:  the certificate file should be installed into the JDK’s certificate store.

Perform the following steps to enable LDAPS for the connection:

1. Obtain the certificate file for the Active Directory server that you are trying to connect to. Although setting up Active Directory for LDAPS is beyond the scope of this article, there is a thorough guide available here:
   1. Active Directory LDAP over SSL

   It may be possible to also export the certificate from a browser like FireFox so that it can then be imported into your JDK’s truststore.

2. Once the certificate file has been obtained, it will need to be added to the JDK truststore. By default, the JDK will use ‘cacerts’ as its truststore, and it will be located in:<Install Location>\jdk\jre\lib\security\cacerts
3. By default, the ‘cacerts’ truststore has a password of ‘changeit’.
4. To import the certificate, the ‘keytool’ application may be used.  The ‘keytool’ application is provided as part of the JDK installation. It can be run from the command line, and will be found in the “jdk\bin” directory of your JDK installation.
5. Assuming the certificate file is “ad-myserver.crt”, the following commands will install the certificate into the “cacerts” truststore:
   1. To import your certificate:
      

      keytool -keystore cacerts -import -trustcacerts -alias ad-myserver -file ad-myserver.crt

   2. To list the installed certificates:
      

      keytool -list -v -keystore cacerts

6. Once this has been done, be sure to update the LDAP URL to utilize “ldaps://” instead of “ldap://”, and to change the port from “389” to “636”. Port 636 is the standard port used for an LDAPS connection. If you are connecting to the Active Directory Global Catalog on port “3268” with LDAP, then you would need to change that to “3269” for LDAPS.
7. Restart the Ephesoft service for the changes to take effect.