Securing your Atlassian applications with Apache using SSL

This page explains how to configure HTTPS (HTTP over SSL) when using Apache as a reverse proxy. You should consider doing this to ensure usernames, passwords and other proprietary data are encrypted when accessing your applications over the internet.

The instructions on this page apply to the following Atlassian server applications: 

• JIRA server applications (JIRA Software Server, JIRA Core, JIRA Service Desk)
• Confluence Server
• Bamboo Server
• Bitbucket Server
• Fisheye
• Crucible
• Crowd

In the examples that follow on this page, <atlassianapp> refers to the name of any of the Atlassian server applications above.

Prerequisites

You'll need the following:

An SSL certificate from a valid Certificate Authority

An SSL certificate is a set of files that are used to encrypt the communication between a visitor's web browser and your server. They also help to verify your website's identity. We recommend that you use SSL certificates issued and signed by a Certificate Authority (CA), instead of self-signed certificates.

The main benefit of using a certificate issued by a CA is that visitors and other applications connecting to your website will be able to verify your site's identity without errors occurring. This is especially important when you are configuring other applications to talk to your application, such as configuring Application Links between Atlassian applications, as connection failures can occur when using an SSL certificate that wasn't issued by a CA.

Atlassian applications running behind an Apache reverse proxy

You will need to have completed the steps in Connect to your application via a Reverse Proxy over HTTP before continuing. If you're starting from scratch we recommend that you get your reverse proxy working over plain HTTP first, and treat your SSL configuration as a separate step.

Part A. Configure the Atlassian applications

This section describes how to update the proxy configuration of the Tomcat (or Jetty in the case of Fisheye or Crucible) web server bundled with each Atlassian application to run behind an SSL-enabled reverse proxy.

2. Update the Connector configuration

If you're using Fisheye or Crucible, update the proxy host, proxy scheme and the proxy port from the Admin area. See Configuring the Fisheye web server.

If you're using any of the other Atlassian server applications,  configure the Connector directive as follows. Note: If your reverse proxy is set up using mod_proxy_ajp, you can skip this step and move on to Part B below.

For each application, find the normal (non-SSL) Connector directive in the Tomcat server.xml file, and update the scheme and proxyPort attributes inside the Connector directive, as below. You would have already added these attributes when configuring the reverse proxy. You need to change scheme to "https" and proxyPort to the port that Apache is listening for SSL on, e.g. "443", like this:

<Connector port=<default>
	maxThreads=<default>
    minSpareThreads=<default>
    connectionTimeout=<default>
    enableLookups=<default>
    maxHttpHeaderSize=<default>
    protocol=<default>
    useBodyEncodingForURI=<default>
    redirectPort=<default>
    acceptCount=<default>
    disableUploadTimeout=<default>
	proxyName="<subdomain>.<domain>.com"
	proxyPort="443"
    secure="true"
	scheme="https"/>

For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 8.0 HTTP Connector Reference.

Part B. Configure SSL

1. Prepare your environment

Copy your SSL certificate files to the server

There are a few files that make up a typical SSL certificate:

• The Certificate file
  • The Certificate file is the public part of your SSL certificate that anyone connecting will see, and tells clients how to encrypt their data so only your certificate files can decrypt it. The certificate file also includes information about the identity of your site, as well as the Certificate Authority (CA) that issued your certificate, to prove to the client that you are who you say you are.
• The Certificate Key file
  • The Certificate Key file is the private part of your SSL certificate. Your Certificate file contains the information required to decrypt the data received from clients that encrypted their data with your public-facing certificate. Without this, data encrypted with your Certificate file can't be read, which means people can't use your public Certificate to impersonate you.
• The Certificate Chain file (optional)
  • Much in the same way that the Certificate file verifies your site's identity, the Certificate Chain file verifies the CA's identity. If your SSL certificate was issued by a CA that a connecting client doesn't recognise, the client will look for a Certificate Chain file that verifies the CA's identity, and therefore your site's identity. Even though they aren't strictly required, a Certificate Chain file helps to ensure your SSL configuration is compatible across the widest pool of clients.

These files need to be copied somewhere on your server where Apache can access them, and should be owned by the root user. It's also possible to use a self-signed certificate, however we don't recommend using self-signed certificates in production.

Enable the Apache SSL module

You need to enable SSL support in Apache before configuring an SSL certificate.

sudo a2enmod ssl

sudo yum install mod_ssl

LoadModule ssl_module modules/mod_ssl.so

2. Update your VirtualHost configuration

Before you begin, your current VirtualHost reverse proxy configuration should look like this:

<VirtualHost *:80>
    ServerName <subdomain>.<domain>.com
     
    ProxyRequests Off
    
    <Proxy *>
         Require all granted
    </Proxy>
 
    ProxyPass /<contextpath> http://<domain>:<port>/<contextpath>
    ProxyPassReverse /<contextpath> http://<domain>:<port>/<contextpath>
</VirtualHost>

If you're using mod_proxy_ajp rather than mod_proxy_http for your reverse proxy configuration, the example proxy URL's above will begin with ajp:// instead of http:// as shown above. The steps to update your VirtualHost configuration with SSL support are identical for either proxy type.

Change the listening port

You need to modify your existing VirtualHost configuration to listen for HTTPS connections instead of HTTP connections. The first step is to change the VirtualHost's listening port to the HTTPS port to the port you will be listening for HTTPS connections on, 443 by default:

<VirtualHost *:443>
    ...
</VirtualHost>

Add your SSL certificates

To activate SSL inside your VirtualHost and attach your certificate files, add the following lines to the end of your VirtualHost configuration:

<VirtualHost *:443>
    ...
 
    SSLEngine On
    SSLCertificateFile /path/to/your/cert.pem
    SSLCertificateKeyFile /path/to/your/privkey.pem
    SSLCertificateChainFile /path/to/your/chain.pem
</VirtualHost>

Redirect HTTP to HTTPS

To enforce the use of secure connections to your server, you should redirect HTTP to HTTPS. You can do this by adding a new VirtualHost that listens on the original HTTP port:

<VirtualHost *:80>
    ServerName <subdomain>.<domain>.com
    Redirect Permanent /<contextpath> https://<subdomain>.<domain>.com/<contextpath>
</VirtualHost>

Your full VirtualHost configuration should end up looking similar to the following example:

<VirtualHost *:443>
    ServerName <subdomain>.<domain>.com
     
    ProxyRequests Off
    
    <Proxy *>
         Require all granted
    </Proxy>
 
    ProxyPass /<contextpath> http://<domain>:<port>/<contextpath>
    ProxyPassReverse /<contextpath> http://<domain>:<port>/<contextpath>
 
    SSLEngine On
    SSLCertificateFile /path/to/your/cert.pem
    SSLCertificateKeyFile /path/to/your/privkey.pem
    SSLCertificateChainFile /path/to/your/chain.pem
</VirtualHost>
 
<VirtualHost *:80>
    ServerName <subdomain>.<domain>.com
    Redirect Permanent /<contextpath> https://<subdomain>.<domain>.com/<contextpath>
</VirtualHost>

If you're using Confluence 6.0 or later with Synchrony (which is required for collaborative editing), you'll need to use Apache 2.4...

Use the following directives and location blocks in the virtual host block:
<VirtualHost *:443>
    ServerName <subdomain>.<domain>.com

    ProxyRequests Off

    <Proxy *>
        Require all granted
    </Proxy>
     
    SSLEngine On
    SSLCertificateFile /path/to/your/cert.pem
    SSLCertificateKeyFile /path/to/your/privkey.pem
    SSLCertificateChainFile /path/to/your/chain.pem

    ProxyPass /synchrony http://<domain>:8091/synchrony

    <Location /synchrony>
        Require all granted
        RewriteEngine on
        RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
        RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
        RewriteRule .* ws://<domain>:8091%{REQUEST_URI} [P]
    </Location>

 	ProxyPass /confluence http://<domain>:8090/confluence
    ProxyPassReverse /confluence http://<domain>:8090/confluence

    <Location /confluence>
        Require all granted
    </Location>

</VirtualHost>
 
<VirtualHost *:80>
    ServerName <subdomain>.<domain>.com
    Redirect Permanent /confluence  https://<subdomain>.<domain>.com/confluence
    Redirect Permanent /synchrony   https://<subdomain>.<domain>.com/synchrony
</VirtualHost>

The new directives inside the virtual host blocks perform these functions:

Configure directives for a particular virtual host

<VirtualHost *:443>

Use the character * as a wildcard to match all IP addresses, with the default https port of 443. This causes Apache to match requests on the ServerName values of the virtual hosts.

See the Apache 2.4  VirtualHost documentation.

Enable the SSL engine

SSLEngine On

This directive simply tells apache that SSL is being used for this virtual host.

See the Apache 2.4  SSLEngine documentation.

Configure the certificate file

SSLCertificateFile /path/to/cert.pem

This is the full path to your certificate file on disk. If the path to your certificate file contains spaces, the path should be enclosed in double quotes.

See the Apache 2.4  SSLCertificateFile documentation.

Configure the certificate private key file

SSLCertificateKeyFile /path/to/privkey.pem

This is the full path to your certificate private key file on disk. If the path to your private key file contains spaces, the path should be enclosed in double quotes.

See the Apache 2.4  SSLCertificateKeyFile documentation.

Configure the certificate chain file

SSLCertificateChainFile /path/to/chain.pem

This is the full path to your certificate private key file on disk. This is optional, but should be configured if present. If the path to your private key file contains spaces, the path should be enclosed in double quotes.

See the Apache 2.4  SSLCertificateChainFile documentation.

Redirect HTTP to HTTPS

Redirect permanent /<contextpath> https://<subdomain>.<domain>.com/<contextpath>

The Redirect permanent directive tells anyone who connects that the resource they're looking for has permanently moved to a new location. In this instance it tells browsers or other software that might connect to Apache that your application has moved from its http URL to its new https URL.

It's also possible to configure http to https redirection in Apache using the mod_rewrite module instead of Redirect permanent, however Apache recommends using Redirect over mod_rewrite where possible.

See the Apache 2.4 When not to use mod_rewrite documentation.

3. Override Apache's Default SSL configuration

Apache includes some supplemental configuration files by default, including default SSL configuration. If the default SSL configuration is loaded before your VirtualHost it can cause issues with how the certificate chain is presented to clients. Under some circumstances this means your application may appear to work over SSL in the browser, but other applications may detect the invalid configuration and fail to connect.

The default SSL configuration file is located in  /etc/httpd/conf.d/ssl.conf . If your VirtualHost directives are contained inside your own  .conf file in this directory, you simply need to make sure your  .conf file appears alphabetically before  ssl.conf , as files from this directory are loaded in alphabetical order.

If your VirtualHost directives have been written directly to /etc/httpd/conf/httpd.conf then you need to locate the following lines and make sure they appear after your VirtualHost entries, and not before:

# Supplemental configuration
#
# Load config files in the "/etc/httpd/conf.d" directory, if any.
IncludeOptional conf.d/*.conf

4. Restart Apache

Debian and Ubuntu

Restart Apache from the command line using:

$ sudo service apache2 restart

Fedora and CentOS

Restart Apache from the command line using:

$ sudo apachectl graceful

You can also use systemd to restart Apache. On CentOS, for example, use:

$ sudo systemctl restart httpd.service

Windows

You can stop and start the Apache service by going to Control Panel > Administrative Tools > Services , look for "Apache2" and select it. Now, on the menu bar select the stop button (square) and wait for the status of the service to change to 'Stopped'. Once the service has stopped select the start button (triangle) and wait for the status to change to 'Started'.

5. Restart each Atlassian application

Now, restart each Atlassian application. See the "stopping and starting" instructions above. 

Check you can access them using the new URLs.

6. Update the application Base URL

For each Atlassian application, update the Base URL to use the https protocol instead of http (such as  https://www.example.com/<atlassianapp>).

Part C. Test your SSL configuration

The most important step of configuring SSL is thoroughly testing your configuration to make sure it is compatible across browsers and other applications. It's possible for SSL to work fine in a browser, but fail when other applications connect. This can cause failures in systems that connect to your application. Some examples of things that might be connecting to your application:

• Application links
• Third-party plugins
• Scripts or tools that use REST APIs
• Application-specific features (remote agents in Bamboo, Smart Mirror servers in Bitbucket Server, etc.)

These kinds of failures may not be immediately obvious, and by the time they are discovered it can be much more difficult to narrow down the cause. Because of this it's essential to test your SSL configuration immediately so you can correct configuration issues that would otherwise be difficult to detect and diagnose later on.

Below are three tests that we recommend you run. It's important that you run all of the tests, as in many cases only one out of three tests will detect a failure. 

1. Browser testing

The simplest test is to access your application via a web browser. Check that the following items are true:

• Accessing your application via the non-HTTPS url, e.g. http://<subdomain>.<domain>.com it automatically redirects to https://<subdomain>.<domain>.com
• No warnings or pop up dialogs appear
• A lock icon appears next to the website address in the address bar
• Clicking on the lock icon and clicking Details or Show Certificate shows that the certificate is valid, and the CA that issued it

2. SSLPoke

SSLPoke is a simple Java utility created by Atlassian to help diagnose SSL issues. This test relies on the local Java installation's own store of trusted certificate authorities, so this test is best run from systems that you plan to connect to your application, e.g. servers hosting existing Atlassian applications.

The KB article Unable to connect to SSL services due to "PKIX Path Building Failed" error covers the steps to download and run the SSLPoke utility. When using SSLPoke from another server that needs to connect to your app, it's important to make sure the version of Java being used is the same one used by that server to run its applications.

3. OpenSSL

Most unix-like systems should have OpenSSL binaries installed, and binaries are also available for Windows. The OpenSSL test validates both your certificate and the certificate chain, which helps to catch more obscure validation issues.

To run the OpenSSL test, run the following command: 

openssl s_client -connect <subdomain>.<domain>.com:443

This test will return a lot of information about your certificate. If successful, the last line of the output should read: 

Verify return code: 0 (ok)
---

Once you've completed the above tests, you're done!

A note on mixed content

When browsers load content from an HTTPS URL, if any non-HTTPS content is included the browser will block the non-HTTPS content for security reasons. This is known as mixed content blocking. If there are other Atlassian applications that will be connecting to your application, we recommend you set up all apps to run over HTTPS, as some integration functions require loading content from the remote app.