Project

General

Profile

Actions
History

Connecting to SSL services

Still need help?

The Atlassian Community is here for you.

Ask the community

Atlassian applications allow the use of SSL within our applications, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian can not guarantee providing any support for it.

  • If assistance with conversions of certificates is required, please consult with the vendor who provided the certificate.
  • If assistance with configuration is required, please raise a question on Atlassian Answers.

This page describes how to get web applications like JIRA and Confluence connecting to external servers over SSL, via the various SSL-wrapped protocols. For instance, you may want to:

  • Refer to an https://... URL in a Confluence macro.
  • Use an IMAPS server to retrieve mail in JIRA.
  • Use SMTP over SSL (SMTPS) to send mail in JIRA.
  • Connect to a LDAP directory over SSL.
  • Set up Trusted Applications over SSL.

If you want to run JIRA itself over SSL, see Running JIRA applications over SSL or HTTPS or Integrating JIRA with Apache using SSL.

Add SSL Certificates automatically!

We now have a JIRA SSL Atlassian Labs plugin for this process. Please install and use the plugin before going through these docs.

Problem Symptoms

Attempting to access URLs that are encrypted with SSL (for example HTTPS, LDAPS, IMAPS) throws an exception and JIRA refuses to connect to it. For example:

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
 at com.sun.mail.imap.IMAPStore.protocolConnect(IMAPStore.java:441)
 at javax.mail.Service.connect(Service.java:233)
 at javax.mail.Service.connect(Service.java:134)

This is the same as the following error that's generated in Chrome when visiting a page that's encrypted with a self-signed certificate, except Java can't "Proceed anyway", it just refuses the certificate:

The Cause

Whenever JIRA attempts to connect to another application over SSL (e.g.: HTTPS, IMAPS, LDAPS), it will only be able to connect to that application if it can trust it. The way trust is handled in the Java world (this is what JIRA is written in) is that you have a keystore (typically $JAVA_HOME/lib/security/cacerts) or also known as the trust store. This contains a list of all the known CA certificates and Java will only trust certificates that are signed by those CA certificate or public certificates that exist within that keystore. For example, if we look at the certificate for Atlassian:

We can see the *.atlassian.com certificate has been signed by the intermediate certificates, DigiCert High Assurance EV Root CA and DigiCert High Assurance CA-3. These intermediate certificates have been signed by the root Entrust.net Secure Server CA. Those three certificates combined are referred to as the certificate chain. As all of those CA certificates are within the Java keystore (cacerts), Java will trust any certificates signed by them (in this case, *.atlassian.com). Alternatively, if the *.atlassian.com certificate was in the keystore, Java would also trust that site.

This problem comes from a certificate that is either self-signed (a CA did not sign it) or the certificate chain does not exist within the Java keystore. Subsequently, JIRA doesn't trust the certificate and fails to connect to the application.

Resolution

In order to resolve this, the public certificate need to be imported in the Java keystore that JIRA uses. In the example above, this is *.atlassian.com and we cover how to install it below.

If you're unable to install Portecle on the server or prefer the command line please see our Command Line Installation section below.

Obtain and Import the Server's Public Certificate

  1. Download and install the Portecle app onto the server that runs JIRA.
    (warning) This is a third-party application and not supported by Atlassian.
  2. Ensure the <JAVA_HOME> variable is pointing to the same version of Java that JIRA uses. See our Setting JAVA_HOME docs for further information on this.
    (info) If running on a Linux/UNIX server, X11 will need to be forwarded when connecting to the server (so you can use the GUI), as below:

Updated by Vishal Pandita 9 days ago · 1 revisions