User Tools

Site Tools


jira_self_signed_cert

JIRA Self Signed Cert And How to Handle It

If you are hosting a local instance of JIRA and have a self-signed cert than you will need to perform the following steps. This is necessary because Java won't trust this endpoint without providing the certificates to it.

How to Identify

JIRA has documentation on this issue as it is relatively common. They have a document for Connecting to SSL Services as well as How to resolve it.

In the 2nd link Jira provides a download link towards a file named SSLPoke.class. This is a helpful tool for diagnosing the issue. If you download it and copy it over to your VM you can run it by opening up the terminal or command prompt, changing directory to where SSLPoke.class is located, and executing the following command:

java SSLPoke example.atlassian.net 443

You will likely see the following from executing the SSLPoke or through the Repeater Agent.

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

How to Fix

Jira provides some documentation on how to address this issue, however we have a slightly different recommendation. You can follow the following steps listed here. This assumes you have java installed on the system already.

This is a 3 step process of:

  1. Getting and setting up our utility
  2. Running the utility to generate the new keystore with the new certificates
  3. Copying over the new keystore to Java can utilize it

Download and Setup of the Utility

Running the Utility

  • Run the following command, replacing example.attlassian.net with your Jira instance
java -jar InstallCert.jar example.atlassian.net

This will open a connection to the endpoint specified and will throw an SSLException if it cannot currently connect, which is expected. It will then say “Server sent 2 certificate(s)” - this may be 1-3 certificates.

  • Following this press 1 to accept the 1st certificate and add it to the keystore
  • Repeat this whole process for certificate 2 and 3 as necessary

Moving Over the Updated Keystore

Once this is complete you will have a new keystore located at the directory you are currently in. This is the file named jssecacerts. i.e. we have a new keystore file now and we just need to swap it in so Java can utilize it.

  • Go to the directory that your Java is installed in
  • Within it there should be a file named cacerts located in the /lib/security path of the Java directory
  • Rename this existing file to cacerts.backup (you could also delete it)
  • Copy in the jssecacerts file into here
  • Rename jssecacerts to cacerts

Following this you can re-test it with the SSLPoke from Jira or restart the Repeater Agent.

Notes

If at any point Java or the keytool asks for the certificate password, the default password is generally “changeit”.

jira_self_signed_cert.txt · Last modified: 2017/10/10 09:45 by jackson.davenport