Adding custom TLS certificates to OL Connect's Java certificate store

When OL Connect communicates with a server using the TLS protocol, the certificate that server provides must be verified. If OL Connect cannot verify the certificate, communication will fail and this will result in an error message in OL Connect. This can happen when a server uses custom certificates.

Servers that can use a custom certificate include:

  • Email servers (SMTP), such as a private email server that can only be reached from an intranet network.

  • An antivirus product that scans email, pretending to be an SMTP email server, and relays the email communication to the real SMTP server.

A certificate usually has a parent certificate, often an intermediate certificate, which usually refers to the root certificate. OL Connect must have, or be able to obtain, all of these certificates.
The intermediate certificate is sometimes provided by the server OL Connect communicates with, or there is a download link in the server's certificate. OL Connect downloads intermediate certificates automatically (as of version 2022.2).
The root certificate must be a certificate that Connect trusts, in other words, a certificate that resides in the certificate store. With custom certificates, OL Connect may not be able to find the root certificate.

A certificate store is also called a key store. Windows has a central certificate store, but as a Java application, OL Connect does not use that store. Like most web browsers, it uses its own certificate store. Java stores the certificate store in a file usually located in the JRE or JDK folder. You can have multiple Java installations on your machine and therefore multiple certificate stores. OL Connect comes with its own JRE in the Program Files folder.

The OL Connect Workflow Server does not have this issue with custom certificates, so if an email server has a custom certificate, the Secure Email Output plug-in works correctly with that email server. However, the Create Email Content plugin uses the OL Connect Server to actually send email; in that case OL Connect's Java certificate store is used. If the custom certificate is not installed there, it will need to be added.

Installing a custom certificate

To import a certificate into OL Connect's Java certificate store, follow these steps:

  1. Stop all OL Connect applications and services

  2. Create a backup of the certificate store file:

    C:\Program Files\Objectif Lune\OL Connect\Plugins\com.objectiflune.jre.win32.win32.x86_64_17.0.6.10-OL-129-46eb7b0a\jre\lib\security\cacerts

    Note: The version number of the JRE folder is different for each version of Connect. Check the name on your file system.

  3. Open a Command Prompt as Admin.

  4. Type:

    cd "C:\Program Files\Objectif Lune\OL Connect\Plugins\com.objectiflune.jre.win32.win32.x86_64_17.0.6.10-OL-129-46eb7b0a\jre\lib\security"

    Note: Check the folder name on your file system.

  5. Place the root certificate file in the Desktop folder.

  6. In the command prompt type this (change the path to the actual location and name of the certificate file you saved):

    ..\..\bin\keytool -import -trustcacerts -keystore cacerts -storepass changeit -noprompt -file "C:\Users\Administrator\Desktop\MyRoot.crt"

  7. A message should be displayed, saying: "Certificate was added to the keystore".

  8. Restart Connect Designer and Server and verify that the OL Connect Server can now communicate with he other server using the TLS protocol.

Note: If you need to import a certificate into OL Connect's certificate store, you must do so every time you install or upgrade Connect, since the JRE folder will get replaced during the upgrade process..