SSL and application link troubleshooting guide
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:
Common SSL errors with application links
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). |
|
The remote certificate may be in the wrong location in the file system. |
|
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. |
|
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
Troubleshoot general SSL errors with application links
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
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:
Application | server.xml location |
---|---|
Bamboo | <install-path>/conf/ |
Confluence | <install-path>/conf/ |
Crowd | <install-path>/apache-tomcat/conf/ |
Crucible | As for Fisheye. |
Fisheye | The 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 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 |
If you are on any of these later releases but your We recommend that you copy |
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
Import a certificate into a trust store
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
.