Running Confluence Over SSL or HTTPS

Atlassian applications allow the use of SSL within our products, however Atlassian Support does not provide assistance for configuring it. Consequently, Atlassian cannot guarantee providing any support for it.

  • If assistance with conversions of certificates is required, please consult with the vendor who provided the certificate.
  • If assistance with configuration is required, please raise a question on Atlassian Answers.

This document tells you how to configure Confluence to enable access via HTTPS (HTTP over SSL), so that your Confluence logins and data are encrypted during transport to and from Confluence. SSL encryption is a good way to safeguard your Confluence data and user logins from being intercepted and read by outsiders.

These instructions apply to the following platforms:

  • Confluence - Apache Tomcat is the application server shipped with Confluence, and is the only supported application server.
    If you are using Apache HTTP Server (httpd) or NGINX, see Apache with mod_proxy or Running Confluence behind NGINX with SSL for instructions on how to terminate an SSL connection at the external web server. 
  • Java 8 - JDK 1.8 is the supported Java version for Confluence. Note that you need the JDK, since it includes the keytool utility used in the instructions below. The JRE is not enough. 

(info) The default connector port for Confluence is 8090.

On this page:

Step 1. Create or Request a New SSL Certificate

You will need a valid SSL certificate before you can enable HTTPS. If you already have a certificate prepared, skip to step 2 below.

You can choose to create a self-signed certificate or to use a certificate issued by a certificate authority (CA, sometimes also called a 'certification authority'). We described both options below.

If you're not comfortable using command line utilities KeyStore Explorer is a useful GUI replacement for the Java Keytool command line.

Certificate Option 1 – Create a Self-Signed Certificate

Self-signed certificates are useful if you require encryption but do not 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.

Follow the steps below to generate a certificate using Java's keytool utility. This tool is included in the JDK.

  1. Use Java's keytoolutility to generate the certificate:

    Many SSL issuers (including but not limited to GoDaddy and RapidSSL) are now requiring a 2048-bit key size. To generate a key with 2048-bit encryption, add '-keysize 2048' to these queries.
    • On Windows, run the following command at the command prompt:

      "%JAVA_HOME%\bin\keytool" -genkeypair -keysize 2048 -alias tomcat -keyalg RSA -sigalg SHA256withRSA
    • On OS X or UNIX-based systems, run the following command at the command prompt:

      $JAVA_HOME/bin/keytool -genkeypair -keysize 2048 -alias tomcat -keyalg RSA -sigalg SHA256withRSA
  2. When asked for a password:
    • Specify the password you want to use for the certificate (private key). Note that the password text will not appear as you type it.
    • Make a note of the password you choose, because you will need it in the next step when editing the configuration file.
    • The default password is 'changeit'.

      Tomcat has a known issue with passwords containing special characters. You should use a password that only contains alphanumeric characters.

  3. Follow the prompts to specify your name, organization and location. This information is used to construct the X.500 Distinguished Name (DN) of the entity. The CN ("What is your first and last name?") must match the fully-qualified hostname of the server running Confluence, otherwise Tomcat will not be able to use the certificate for SSL. For example for a Confluence running on a server named "confluence.example.com":
    CN=confluence.example.com, OU=Java Software Division, O=Sun Microsystems Inc, C=US
  4. Enter 'y' to confirm the details.
  5. When asked for the password for 'tomcat' (the alias you entered in the keytool command above), press the 'Enter' key. This specifies that your keystore entry will have the same password as your private key. You MUST use the same password here as was used for the keystore password itself. This is a restriction of the Tomcat implementation.
  6. You certificate is now ready. Go to step 2 below.

Certificate Option 2 – Use a Certificate Issued by a Certificate Authority

When running Confluence in a production environment, you will need a certificate issued by a certificate authority (CA, sometimes also called a 'certification authority') such as VeriSign, Thawte or digicert. The instructions below 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, as described in the previous section.
  2. Use the keytool utility to generate a CSR, replacing the text <MY_KEYSTORE_FILENAME> with the path to and file name of the .keystorefile generated for your local certificate:

    keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>
    
  3. Submit the generated file called certreq.csr to your chosen certificate authority. Refer to the documentation on the CA's website 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>

    Please note that some CAs require you to install an intermediate certificate before importing your certificate. Please refer to your CA documentation to successfully install your certificate.

     

If you receive an error, and you use Verisign or GoDaddy, you may need to export the certificate to PKCS12 format along with the private key. 

  1. First, remove the certificate added above from the keystore:

    keytool -delete -alias tomcat -keystore <MY_KEYSTORE_FILENAME>
  2. Then export to PKCS12 format:

    openssl pkcs12 -export -in <MY_CERTIFICATE_NAME> -inkey <MY_PRIVATEKEY_NAME> -out <MY_PKC12_KEYSTORE_NAME> -name tomcat -CAfile <MY_ROOTCERTIFICATE_NAME-alsoCalledBundleCertificateInGoDaddy> -caname root
  3. Then import from PKCS12 to jks:

    keytool -importkeystore -deststorepass <MY_DESTINATIONSTORE_PASSWORD> -destkeypass <MY_DESTINATIONKEY_PASSWORD> -destkeystore <MY_KEYSTORE_FILENAME> -srckeystore <MY_PKC12_KEYSTORE_NAME> -srcstoretype PKCS12 -srcstorepass <MY_PKC12_KEYSTORE_PASSWORD> -alias tomcat

 

Step 2. Modify the Server Configuration File in your Confluence Installation

  1. Edit the server configuration file at this location: <CONFLUENCE_INSTALLATION>/conf/server.xml.
  2. Uncomment the following lines:

    <Connector port="8443" maxHttpHeaderSize="8192"
         maxThreads="150" minSpareThreads="25"
         protocol="org.apache.coyote.http11.Http11NioProtocol"
         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 the text <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. Save the server configuration file.

(warning) Avoid removing the http connector, as the Synchrony proxy health check, still requires HTTP. If you do not 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. 

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 will need to update your server configuration file as outlined below, so that Tomcat can find the certificate.

  1. Edit the server configuration file at this location: <CONFLUENCE_INSTALLATION>/conf/server.xml
  2. Add the attribute keystoreFile="<MY_CERTIFICATE_LOCATION>" to the Connectorelement, so that the element looks like this:

            <Connector port="8443" maxHttpHeaderSize="8192"
                       maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                       enableLookups="false" disableUploadTimeout="true"
                       acceptCount="100" scheme="https" secure="true"
                       clientAuth="false" sslProtocol="TLS" 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 server configuration file.

Step 4. Change your Confluence Base URL to HTTPS

  1. In your browser, go to the Confluence Administration Console.
  2. Change the Server Base URL to HTTPS. See the documentation on configuring the server base URL.
  3. Restart Tomcat 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.

(info) 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 SE 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: https://tomcat.apache.org/tomcat-8.0-doc/config/http.html

            <Connector port="8443" address="your.confluence.url.com" maxHttpHeaderSize="8192"
                       maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                       enableLookups="false" disableUploadTimeout="true"
                       acceptCount="100" scheme="https" secure="true"
                       clientAuth="false" sslProtocol="TLS" SSLEnabled="true"
                       URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"
                       keystoreFile="<MY_CERTIFICATE_LOCATION>"/>
    
  • Protection for logins only or for individual spaces: As of Confluence 3.0, Atlassian does not support HTTPS for logins only or for specific pages. We support only site-wide HTTPS. To see the reasoning behind this decision, please see CONF-18120 and CONF-4116.

Troubleshooting

  • Problems with Internet Explorer being unable to download attachments: Applying SSL site wide can prevent IE from downloading attachments correctly. To fix this problem, edit <CONFLUENCE_INSTALLATION>/conf/server.xml and add the following line within the <Context ... />element:

    <Valve className="org.apache.catalina.authenticator.NonLoginAuthenticator"
           disableProxyCaching="true" securePagesWithPragma="false" />
Last modified on Mar 27, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.