Using KeyStore Explorer to configure certificate stores for secure LDAP (LDAPs) in eDiscovery

Description

Setting up secure LDAP (LDAPs) authentication for eDiscovery requires importing a valid certificate or certificate chain into the Java keystore file(s).  This process can be daunting if done using the keytool command line interface with certificates provided in various formats and naming conventions.  This article provides a method to streamline that process and take out some of the guesswork using an open source tool called KeyStore Explorer..  

Steps

Setup:

1. Download and install KeyStore Explorer on the eDiscovery primary server following the defaults
2. Create a directory to contain the certificate keystores that will be modified. 
   In this article, it is D:\LDAPs Temp\
3. Create two subdirectories, one for backup copies of the keystore files and the other for keystore file modification.
   In this article, the folders are D:\LDAPs Temp\Cacerts Backup\ and D:\LDAPs Temp\Work Folder.
4. Copy a known-good cacerts keystore file to both the backup and working directories created in step 3.
   Note:  In eDiscovery version 10.0 and above, also copy a known-good cacerts.bcfks file.
   These files can be found in the C:\jdk-8u###-windows-x64\jre\lib\security folder.
   Ensure you copy these from the JDK folder of the Java version currently in use by eDiscovery.

Certificate Import:

1. Run Keystore Explorer and open the cacerts keystore in the working directory.
   You will be prompted for the keystore password.
   This password must match the unencrypted password used in the eDiscovery property esa.cert.keystore.password
2. With the keystore file open, go to Examine > Examine SSL to query the domain controller or global catalog server used for LDAPs authentication for its associated certificate(s).
   A. For SSL Host, enter the FQDN of the domain controller or global catalog server.
   B. For SSL Port, enter the port used to connect to the domain controller or global catalog server.
   Notes:  The SSL Host name should match the one defined in eDiscovery property esa.ldap.connectionURL and the SSL Port should match the one defined at the end of the eDiscovery property esa.ldap.connectionURL
   ► For connection to a domain controller: ldaps://server FQDN:636
   ► For connection to a global catalog server: ldaps://server FQDN:3269
   
   
   
   
    
3. ​​​​​​The Certificate Hierarchy will show one or more certificate used by the authenticating server. 
   If more than one are shown, each of these certificates will need to be imported into the keystore to complete the certificate chain. 
   The certificates in a chain can be imported in any order.
   
   
    
4. To import, highlight a certificate and click the Import button. 
   A. You will be prompted to Enter Alias for the certificate. 
        You can leave it as the default of "Server Name (Certificate Name)" or enter a friendly name.
         If multiple certificates are shown in the chain, creating a similar alias for each aids in grouping them together in Keystore Explorer.
   ►For example, LDAPsCaRoot, LDAPsCaIntermediate, LDAPsCaSSL
5. Repeat the Import for each certificate in a chain, if multiple are shown.
6. Repeat the above steps for the cacerts.bcfks file in eDiscovery version 10.0 and above.

Deployment and Testing:

1. Once the domain certificates have been imported into the keystore(s), copy those files to the JDK x64\jre\lib\security folder, replacing the existing files.
   1. In version 10.2 and above, the file(s) should be placed in the JDKx64\jre\lib\security folder, not the jre8\jre\lib\security folder.
2. In eDiscovery version 10.0 and above, also copy the cacerts.bcfks file to D:\CW\v100\scratch\temp.  Delete the existing Legal Hold keystore file named cert and rename the cacerts.bcfks file to cert.
3. Restart eDiscovery services using options 3 and 4 in the Clearwell Utility.
4. To test LDAPs functionality, log into eDiscovery with System Manager credentials and navigate to System > Users and attempt to Add an enterprise user by typing at least the first three characters of a first or last name of a users existing in the domain user base. 
   If working, the LDAP server should return one or more names.