Outbound Connectivity Error: PKIX path building failed

Issue

When making a configuration change to an On-Premises (EOP) installation of the Contrast UI Server that requires outbound secure connectivity, for example: 

• Enabling "Contrast Hub" connectivity in System Settings->Internet Settings
• Configuring a secure LDAP server as the desired authentication method in System Settings->Authentication
• Enabling any of the integrations, such as JIRA, in Organization Settings->Integrations

the "Test Connection" fails and an entry such as the following is seen in the contrast.log file:

javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

or, in the JIRA example, an error such as the following is seen in the UI:

Cause

The most likely cause of this error is that the server (such as one of the integrations - for example a bugtracker like JIRA, or for an auth server such as LDAP) uses either a self-signed or privately-signed certificate, or (in all cases) outbound traffic from the Contrast Server is passing through a network device such as a proxy which is rewriting the certificate.  The Contrast EOP Server runs under Tomcat which is a Java Application Server and, by default, all JREs come with a set of trusted CAs that contains the usual commercial CA certificates - DigiCert, GlobalSign etc.  If the outbound connection sees a certificate that is self-signed or is signed by an internal CA then the JVM will be unable to build the chain of trust, resulting in a handshaking failure when connecting.

Resolution

Acquire the certificate

You can do that using openssl like so - for example for an LDAPS server:

openssl s_client -showcerts -connect {ldap server hostname}:636 </dev/null 2>/dev/null|openssl x509 -outform PEM > ldapserver.pem

Or for connectivity to the Contrast Hub:

openssl s_client -showcerts -connect hub.contrastsecurity.com:443 </dev/null 2>/dev/null|openssl x509 -outform PEM > hub.pem

Trust the certificate

From the {contrast home} directory, you can either add the target server's certificate to the default JRE Truststore:

jre/bin/keytool -import -alias <alias name if desired> -trustcacerts -file <pem file from above> -keystore jre/lib/security/cacerts

(This assumes you're using the embedded JRE - if not then replace the paths as necessary to reference the cacerts file for JRE in use.)

The default keystore password is changeit

Alternatively you can create a new Truststore as in the following example, and import the certificate:

mkdir data/conf/ssl
jre/bin/keytool -import -alias <alias name if desired> -file <pem file from above> -keystore data/conf/ssl/truststore.jks

then reference the Truststore in the bin/contrast-server.vmoptions file by adding the following lines:

-Djavax.net.ssl.trustStore=<full path to Truststore>
-Djavax.net.ssl.trustStorePassword=<password you set for the Truststore, if any>