- The remote certificate can't be trusted
- The remote certificate doesn't match the remote host name
- Check if there was a recent upgrade
- Know your network topology
- Check you are using the correct base URL
- Check your SSL certificate configuration
- Check the SSL certificate location
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 targetChecklist of possible causes
Actions you can take
The remote SSL certificate has expired.
- Check the certificate details online (for example using https://www.digicert.com).
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.
- See Check the SSL certificate location below.
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:
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.
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
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.
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
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/
- Windows: C:\Program Files\Atlassian\
- Windows: C:\Atlassian\
Locations in Atlassian application's folder structure:
N/A, replaced by /shared/bitbucket.properties
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 /conf/server.xml .
We recommend that you copy /conf/server.xml into /shared/ that way you won't need to worry about this when you upgrade your instance.
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
(previously called Stash)
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/cacertswhere 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 -file -keystore Import a certificate into a trust store
Using the Java keytool utility, import the certificate into the keystore:
keytool -import -alias -file -keystore 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 /jre/bin/keytool .
| Description | This page is a part of our Application Links Troubleshooting Guide. |
|---|---|
| Product | Jira, Confluence, Bitbucket, Fisheye, Crucible, Bamboo |
| Platform | Serve |
