Adding a certificate to the xMatters Agent

Question 

We are trying to setup an integration between xMatters and another application using the xMatters agent.

When we trigger the workflow, we receive the following error: 

Script failed with message: JavaObject[org.springframework.web.client.ResourceAccessException: I/O error on POST request for "<url>": PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target; nested exception is javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target (org.springframework.web.client.ResourceAccessException)]

It sounds like we have to add the calling system's SSL certificate to the agent's trust store - how do we do that?

Environment

All versions of xMatters - xMatters Agent

Answer

For SSL communication to work, the JRE might need to possess a local copy of the server's public certificate. This is necessary if:

• the server's certificate is self-signed, or
• there is a problem with the server's commercial certificate.

The client's copy is kept in a "trust store", which by default is a file called cacerts in the Java's \jre\lib\security folder.

Back Up the existing cacerts file

Start by making a backup copy of the existing cacert file. In most cases, you'll find this in the Java JDK installation folder (where the agent resides) in the \lib\security folder, and it'll look like something like this:

...\xa\jre\windows\jdk-11.0.4\lib\security

Once you've made a backup copy, continue with the following instructions.

Add the certificate to the trust store

To add a certificate to the JRE's trust store, open a command window, change to Java's jre\bin folder, and run the following command:

keytool -importcert -keystore ../lib/security/cacerts -storepass changeit -file /temp/somecert.cer -alias somecert

• Java's /jre/lib/security/cacerts file is the JRE's default trust store.
• changeit is the default password for any JRE's trust store.
• -file is followed by the path to the certificate that you want to add to the trust store. The certificate should be in either DER (binary) format or X.509 Base-64 encoded text format. JRE 8 will also trust PKCS12-formatted certificates in "compatibility" mode.
• -alias allows you to specify an alias for the certificate, which makes it more convenient to list and manipulate the certificates in the store.

You can view certificates in the store with the keytool -list command. To see only a single certificate, use the -alias argument. For more detail, use -v:

keytool -list -keystore ../lib/security/cacerts -storepass changeit -alias somecert -v

Where can I get a copy of the certificate?

Your calling server's administrator should be able to provide it to you, but you can also export a copy from a browser. Simply browse to the server's URL, and then use the browser's certificate export tool. Use your favorite search engine to look up browser-specific instructions.