Running Confluence Over SSL or HTTPS

These instructions cover terminating SSL at Tomcat, the application server shipped with Confluence. 

If you want to terminate SSL at your web server or proxy, see Apache with mod_proxy or Running Confluence behind NGINX with SSL for examples of how to terminate SSL at an external web server.  

You'll need the JDK for some of the steps in this guide. The JRE is not enough. 

Step 1. Create or request an SSL certificate

You'll need a valid certificate before you can enable HTTPS. If you already have a certificate, skip to step 2.

You can create your own self-signed certificate, or acquire one from a trusted Certificate Authority. 

If your team plans to use the Confluence Server mobile app, you'll need a certificate issued by a trusted Certificate Authority.  You can't use the app with a self-signed certificate, or one from an untrusted or private CA. 

Option 1: Create a self-signed certificate

Self-signed certificates are useful if you require encryption but don't need to verify the identity of the requesting website. In general, you might use a self-signed certificate on a test environment and on internal corporate networks (intranets).

Because the certificate is not signed by a certificate authority (CA), users may receive a message that the site is not trusted and may have to perform several steps to accept the certificate before they can access the site. This usually will only occur the first time they access the site. Users won't be able to log in to your site at all via the Confluence Server mobile app if you use a self-signed certificate. 

In this example, we'll use Java's keytool utility, which is included with the JDK. If you're not comfortable using command line utilities KeyStore Explorer is a useful alternative to the command line.

To generate a self-signed certificate using keytool: 

1. From the command line, run the appropriate command for your operating system:

   Windows

   "%JAVA_HOME%\bin\keytool" -genkeypair -keysize 2048 -alias tomcat -keyalg RSA -sigalg SHA256withRSA

   Linux (and MacOS)

   $JAVA_HOME/bin/keytool -genkeypair -keysize 2048 -alias tomcat -keyalg RSA -sigalg SHA256withRSA

2. When prompted, create a password for the certificate (private key). 

   • Only use alphanumeric characters. Tomcat has a known issue with special characters. 
   • Make a note of the password, you'll need it in the next step. 

   • The default password is 'changeit'.  

3. Follow the prompts to specify the certificate details. This info is used to construct the X.500 Distinguished Name (DN) of the entity. 
   
   
   • First and last name: this is not your name, it is the Common Name (CN), for example 'confluence.example.com'. The CN must match the fully qualified hostname of the server running Confluence, or Tomcat won't be able to use the certificate for SSL. 
   • Organizational unit: this is the team or department requesting the certificate, for example 'marketing'. 
   • Organization: this is your company name, for example 'SeeSpaceEZ'.

   • City, State / province, country code: this is where you're located, for example Sydney, NSW, AU. 

4. The output will look something like the example below.  Hit 'y' to confirm the details.

   CN=confluence.example.com, OU=Marketing, O=SeeSpaceEZ, L=Sydney, ST=NSW, C=AU

5. When asked for the password for 'tomcat', enter the password you created in step 2 (or hit return to use the same . 
   • 'tomcat' is the alias we entered in the keytool command above, it refers to your. 
   • Your keystore entry must have the same password as your private key. This is a Tomcat requirement. 
     
     
6. You certificate is now ready. Go to step 2 below.

Option 2: Use a certificate issued by a Certificate Authority (recommended)

Production environments will need a certificate issued by a Certificate Authority (CA). These instructions are adapted from the Tomcat documentation.

First you will generate a local certificate and create a 'certificate signing request' (CSR) based on that certificate. You will submit the CSR to your chosen certificate authority. The CA will use that CSR to generate a certificate for you.

1. Use Java's keytool utility to generate a local certificate (follow the steps in option 1, above).

2. From the command line, run the following command to generate a certificate signing request.

   keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>

   Replace <MY_KEYSTORE_FILENAME> with the path to and file name of the .keystore file generated for your local certificate.

3. Submit the generated file called certreq.csr to your chosen certificate authority.
    Check your CA's documentation to find out how to do this.
4. The CA will send you a certificate.

5. Import the new certificate into your local keystore:

   keytool -importcert -alias tomcat -keystore <MY_KEYSTORE_FILENAME> -file <MY_CERTIFICATE_FILENAME>

   Some CAs require you to install an intermediate certificate before importing your certificate. You should follow your CA documentation to successfully install your certificate.

Step 2. Modify your Confluence server.xml file

The next step is to configure Confluence to use HTTPS. 

1. Edit <install-directory>/conf/server.xml.

2. Uncomment the following lines:

   <Connector port="8443" maxHttpHeaderSize="8192"
      maxThreads="150" minSpareThreads="25"
      protocol="org.apache.coyote.http11.Http11Nio2Protocol"
      enableLookups="false" disableUploadTimeout="true"
      acceptCount="100" scheme="https" secure="true"
      clientAuth="false" sslProtocol="TLSv1.2"
      sslEnabledProtocols="TLSv1.2" SSLEnabled="true"
      URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"/>

3. Replace <MY_CERTIFICATE_PASSWORD> with the password you specified for your certificate.
4. Make sure that the attribute-value pair SSLEnabled="true" is part of the Connector element, as shown above. If this attribute is not present, attempts to access Confluence will time out.
5. Change the value of maxThreads to be at least 10 threads (or 25%) less than the size of your database connection pool. 48 is usually about right. See HTTP MaxThreads configuration for more information about this. 
6. Save the server configuration file.

 Don't remove or comment out the http connector, as the Synchrony proxy health check, still requires HTTP. If you don't want to include the http connector, you can use the synchrony.proxy.healthcheck.disabled system property to disable the health check. 

You should also not disable the internal Synchrony proxy (by setting the synchrony.proxy.enabled system property to false) as this is known to cause problems when you're terminating SSL at Tomcat. 

 The default connector port for Confluence is 8090.

The Confluence mobile app requires minimum TLS 1.2.

Step 3. Specify the location of your certificate

By default, Tomcat expects the keystore file to be named .keystore and to be located in the user home directory under which Tomcat is running (which may or may not be the same as your own home directory). This means that, by default, Tomcat will look for your SSL certificates in the following location:

• On Windows: C:\users\#CURRENT_USER#\.keystore
• On OS X and UNIX-based systems: ~/.keystore

You may decide to move the certificate to a custom location. If your certificate is not in the default location, you'll need to update your server configuration file as outlined below, so that Tomcat can find the certificate.

1. Edit  <confluence-install-directory>/conf/server.xml

2. Add the attribute keystoreFile="<MY_CERTIFICATE_LOCATION>" to the Connector element, so that the element looks like this:

   <Connector port="8443" maxHttpHeaderSize="8192"
      maxThreads="150" minSpareThreads="25"
      protocol="org.apache.coyote.http11.Http11Nio2Protocol"
      enableLookups="false" disableUploadTimeout="true"
      acceptCount="100" scheme="https" secure="true"
      clientAuth="false" sslProtocol="TLSv1.2"
      sslEnabledProtocols="TLSv1.2" SSLEnabled="true"
      URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"
      keystoreFile="<MY_CERTIFICATE_LOCATION>"/>
   

3. Replace the text <MY_CERTIFICATE_LOCATION> with the path to your certificate, including the path and the name of the .keystore file.
4. Save the configuration file.

Step 4. Change your confluence base URL to HTTPS

1. In your browser, go to 

   Error rendering macro 'excerpt-include'

   User 'null' does not have permission to view the page.

   . 
2. Click Edit. 
3. Change the Server Base URL to HTTPS. See the documentation on configuring the server base URL.
4. Restart Confluence and access Confluence on https://<MY_BASE_URL>:8443/.

Step 5. Add a security constraint to redirect all URLs to HTTPS

Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8090) are still available. Now you need to redirect the URLs to their HTTPS equivalent. You will do this by adding a security constraint in web.xml. This will cause Tomcat to redirect requests that come in on a non-SSL port.

1. Check whether your Confluence site uses the RSS macro. If your site has the RSS macro enabled, you may need to configure the URL redirection with a firewall rule, rather than by editing the web.xml file. Skip the steps below and follow the steps on the RSS Feed Macro page instead.
2. Otherwise, Edit the file at <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/web.xml.

3. Add the following declaration to the end of the file, before the </web-app>tag:

   <security-constraint>
     <web-resource-collection>
       <web-resource-name>Restricted URLs</web-resource-name>
       <url-pattern>/</url-pattern>
     </web-resource-collection>
     <user-data-constraint>
       <transport-guarantee>CONFIDENTIAL</transport-guarantee>
     </user-data-constraint>
   </security-constraint>
   

4. Restart Confluence and access http://localhost:8090. You should be redirected to https://localhost:8443/login.action.

Confluence has two web.xml files. The other one is at <CONFLUENCE_INSTALLATION>/conf/web.xml. Please only add the security constraints to <CONFLUENCE_INSTALLATION>/confluence/WEB-INF/web.xml, as described above.

Notes

• Background information on generating a certificate: The 'keytool -genkeypair' command generates a key pair consisting of a public key and the associated private key, and stores them in a keystore. The command packages the public key into an X.509 v3 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry, identified by the alias that you specify in the command. The Java 11 documentation has a good overview of the utility.

• Custom SSL port: If you have changed the port that the SSL connector is running on from the default value of 8443, you must update the redirectPort attribute of the standard HTTP connector to reflect the new SSL port. Tomcat needs this information to know which port to redirect to when an incoming request needs to be secure.

• Multiple instances on the same host: When running more than one instance on the same host, it is important to specify the address attribute in the <CONFLUENCE_INSTALLATION>/conf/server.xml file because by default the connector will listen on all available network interfaces, so specifying the address will prevent conflicts with connectors running on the same default port. See the Tomcat Connector documentation for more about setting the address attribute:

  <Connector port="8443" address="your.confluence.url.com"
     maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25"
     protocol="org.apache.coyote.http11.Http11Nio2Protocol"
     enableLookups="false" disableUploadTimeout="true"
     acceptCount="100" scheme="https" secure="true"
     clientAuth="false" sslProtocol="TLSv1.2"
     sslEnabledProtocols="TLSv1.2" SSLEnabled="true"
     URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"
     keystoreFile="<MY_CERTIFICATE_LOCATION>"/>

• HTTPS must be configured for your whole site.  It can't be enabled for individual pages or spaces. 
• Before you upgrade Confluence, make a note of the changes you have made to your server.xml and web.xml files.  It is always best to re-apply these changes manually after upgrading, rather than copying over your existing files. 
• TLS 1.2 or 1.3 recommended. The Confluence Server mobile app requires TLS 1.2. If you use Jira and Confluence together, we recommend configuring both applications to use the same TLS version.  

Troubleshooting

• Check the Confluence knowledge base articles on troubleshooting SSL 
• SSL Configuration HOW-TO in the Apache Tomcat 9.0 documentation
• keytool - Key and Certificate Management Tool in the Java 11 documentation