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. 

Windows

For the xMatters Agent on Windows, the cacerts file is located at

<xAHome>\jre\windows\jdk-<version>-jre\lib\security\cacerts

(where <xAHome> is “c:\Program Files\xa” by default, and <version> is the version of the JRE.)

The path to the keytool executable on Windows xAgents is

<xAHome>\jre\windows\jdk-<version>-jre\bin\keytool.exe

Linux

For agents running on Linux, the JRE is installed outside of the xMatters Agent’s part of the filesystem. It’s possible that several different versions of Java are installed on the server. To identify the JRE used by the agent, log on as the user that owns the agent (the “xmatters” user, by default) and paste the following command into a terminal window:

The final line of output should be similar to

In the above example, the cacerts file will be

/usr/lib/jvm/java-21-openjdk/lib/security/cacerts

and the path to the keytool executable will be

/usr/lib/jvm/java-21-openjdk/bin/keytool

Back up the existing cacerts file

You will need to be logged on as a user with administrator rights (on Windows) or sudo privileges (on Linux) to make the changes described in this section.

Navigate to the location of the cacerts file (see above), and make a copy of the file (eg, “cacerts.orig”).

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 -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 -cacerts -storepass changeit -alias somecert -v

From the xMatters Agent home folder, you can also generate a text listing of the entire trust store so you can search for a specific certificate alias:

keytool -v -list -cacerts -storepass changeit  %temp%\cacerts.txt

After running this command, open %temp%\cacerts.txt and search for the certificate alias you imported to confirm that it is present.

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. From a browser on the computer running the xMatters Agent, navigate to the server's URL, click the lock or security icon next to the address bar, and open the connection or certificate details (for example, "Certificate is valid" or "View certificate"). In the certificate viewer, go to the details page and use the export option to save the certificate to a file (commonly .cer or .crt in Base-64 or DER format). Save that file and then use it as the input to the keytool -importcert command above.