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>
<%= heading %>