The first part of this page describes the specific SSL errors that can be diagnosed automatically by application links and the actions you can take to correct those errors.

The second part provides a general troubleshooting guide to help you identify and correct errors that may occur when using HTTPS with application links.

On this page:


The remote certificate can't be trusted

The application link was attempting to communicate over HTTPS with the remote application but can’t trust the remote SSL certificate.

The remote application may be using a self-signed SSL certificate or a certificate that was issued by a certificate authority that isn't known by the local application.

You may see any of these error messages in the Atlassian application logs:

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
Checklist of possible causes
Actions you can take

The remote SSL certificate has expired.

The remote certificate doesn't appear to be issued by a trusted authority (it may have been self-signed).

  • If the certificate was issued by a trusted authority, you may need to install one or more intermediate certificates.
  • If the certificate is self-signed, you can import the certificate into the Java trust store, for the JVM that the local application is using. See Check the SSL certificate location below.
The remote certificate may be in the wrong location in the file system.

Back to top


 


The remote certificate doesn't match the remote host name

The application link was attempting to communicate over HTTPS with the remote application but can’t trust the remote SSL certificate.

The remote SSL certificate can't be trusted because the common name in the certificate doesn't match the URL of the remote application, because details of the certificate can't be verified. The certificate URL should also match the URL used to configure the application link.

You may see the following error message in the Atlassian application logs:

javax.net.ssl.SSLException: hostname in certificate didn't match
javax.net.ssl.SSLException: <message>
Checklist of possible causes
Actions you can take

The remote certificate common name doesn't match the host address URL.

  • Check that the common name (CN) in the certificate matches the host URL (for example using https://www.digicert.com/help/). If it doesn't match, you'll need to replace the certificate.

Back to top


Error messages in the logs

You may see these error messages in the application logs:

  • javax.net.ssl.SSLException: hostname in certificate didn't match
  • 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

Follow a link above for detailed information on this page.

Application log locations

Logging configurationApplication logsTomcat webserver logs
Bamboo <Bamboo installation directory> /logs  
Bitbucket Server / Stash

<Bitbucket home directory>/log

<Stash home directory>/log

<Bitbucket Server installation directory>/logs

<Stash installation directory>/logs

Confluence <Confluence home directory>/logs <Confluence installation directory >/logs
Crowd <Crowd home directory>/logs <Crowd installation directory>/apache-tomcat/logs
Crucible <Crucible installation  directory>/var/log/  
Fisheye <FishEye installation  directory>/var/log/  
JIRA applications <JIRA application home directory>/log <JIRA application installation directory>/logs

Consider enabling the DEBUG level of logging on the application to get more detailed logs – DEBUG adds all stack traces, and includes HTTP response messages.

This section provides a troubleshooting guide to help you identify and correct general errors that occur when using HTTPS (HTTP over SSL) with application links. 

Check if there was a recent upgrade

If your application links have stopped working after a recent upgrade it's possible that your customizations to the application's server.xml file were overwritten. Custom changes can include reverse proxy configuration and HTTPS configuration. You should check that the upgraded server.xml file matches the pre-upgrade server.xml.

The location of your server.xml file depends on your application, operating system, and installation location. 

Common default installation locations for Atlassian applications are:

  • Linux: /opt/atlassian/<application-name>
  • Windows: C:\Program Files\Atlassian\<application-name>
  • Windows: C:\Atlassian\<application-name>

Locations in Atlassian application's folder structure:

Applicationserver.xml location
Bamboo<install-path>/conf/
Confluence<install-path>/conf/
Crowd<install-path>/apache-tomcat/conf/
CrucibleAs for Fisheye.
FisheyeThe Fisheye configuration file is config.xml, see Configuring the Fisheye web server and How to enable Fisheye/Crucible to listen to web requests on additional ports.
JIRA applications<install-path>/conf/
Bitbucket Server 5.0

N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties

Bitbucket Server 4.0 – 4.14<Bitbucket home directory> /shared/server.xml
Stash 3.8 – 3.11

<Stash home directory>/shared/

If you are on any of these later releases but your server.xml does not exist in the directory above, it means that you are running from the <install-path>/conf/server.xml.

We recommend that you copy <install-path>/conf/server.xml into <Stash home directory>/shared/ that way you won't need to worry about this when you upgrade your instance.


Stash 3.7 and earlier<install-path>/conf/

<install-path> refers to where the application was installed on your system.


Know your network topology

There are two common ways to configure secure connections between applications. These approaches determine where SSL certificates should be stored and the application URLs that should be used when setting up application links.

Terminate SSL at a reverse proxy

Clients connect to the reverse proxy over SSL. The reverse proxy communicates over an unsecured connection with the application server.

Terminate SSL at the application server

For installations that do not use a reverse proxy, Tomcat can be configured to allow SSL connections. Terminating at the application server can also be used with a reverse proxy to ensure that the communication between the reverse proxy and application server is secure.

Configure Atlassian applications to use HTTPS

Check you are using the correct base URL

Ensure that your application has the correct base URL defined (including the http or  https protocol) and that you're using that same URL in your application link.

Check your SSL certificate configuration

There are some minimum requirements that your SSL certificate must meet:

  • The certificate common name (CN) must match the host name (the URL address) for the application.
  • The certificate timestamp must still be valid.
  • The certificate must be installed into the correct Java trust store (Atlassian server products are Java applications that bundle the Tomcat application server).
  • The local trust store must contain the certificate for the remote application you're trying to connect to.
  • Intermediate certificates must exist in the trust store.
  • The local and remote certificates must be of the correct format to be imported into the default trust store type (JKS).

To see details of a certificate, visit the application in your browser and click the padlock in the browser address bar. You can also check SSL certificate details online (for example using https://www.digicert.com/help/.

To check that certificates are present in the Java trust store see Check the SSL certificate location below.

Check the SSL certificate location

Java applications such as Atlassian server products expect to find SSL certificates in particular locations in the filesystem.

By default, Java applications use the JRE cacerts trust store, located at:

JAVA_HOME/jre/lib/security/cacerts

where JAVA_HOME is an environment variable that points to the Java installation directory. Note, however, that some Atlassian products may bundle a JRE, in which case they will use the trust store for the JRE.

You can specify alternative stores by specifying JVM arguments when starting the application. See this Oracle documentation for further details.

Typically, you must export the certificate from the remote application and then import it into the local application. This is common when applications are run on separate machines, or are using a bundled JVM.

Export a certificate from a key store

If you have access to the .crt certificate file, you can skip this step.

Using the Java keytool utility, export the certificate:

keytool -export -alias <existing_alias_in_keystore> -file <any_filename_here> -keystore <path/to/keystore>

Import a certificate into a trust store

Using the Java keytool utility, import the certificate into the keystore:

keytool -import -alias <new_unique_alias> -file <any_filename_here_from_above> -keystore <path/to/truststore>

Where is the keytool utility?

The keytool is provided with the Java Runtime Environment (JRE). If you're using a product with a bundled JRE, you can find keytool in <product-install-path>/jre/bin/keytool.

  • No labels
 




 

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.