The instructions on this page describe how to run Jira applications over SSL or HTTPS by configuring Apache Tomcat with HTTPS. This procedure only covers the common installation types of Jira. It is by no means a definitive or comprehensive guide to configuring HTTPS and may not apply to your environment.

Why should you run Jira over SSL or HTTPS? When people access web applications, there is always a possibility that their usernames and passwords can be intercepted by intermediaries between your computer and the ISP/company. It's a good idea to enable access via HTTPS (HTTP over SSL) and make this a requirement for pages where passwords are sent. Note, however, that using HTTPS may result in slower performance.

Before you begin

Please note the following before you begin:

• Support
  Atlassian Support will refer SSL support to the Certificate Authority (CA) that issues the Certificate. The SSL-related instructions on this page are provided as a reference only.
  
  
• Windows installers
  The 'Windows Installer' installs its own Java Runtime Environment (JRE) Java platform, which is used to run Tomcat. When updating SSL certificates, please do so in this JRE installation.
  
  

• Related bugs
  Jira 7.3 and later is affected by two bugs that incorrectly set the protocol in the server.xml file. You can work around this issue by setting the protocol manually.

  Tell me more...

  Two bugs affecting Jira 7.3.0 and later:

  JRASERVER-63734 - Getting issue details... STATUS

  JRASERVER-64082 - Getting issue details... STATUS

  The workaround is to manually edit the server.xml file to change the protocol on your HTTPS connector to:

  protocol="org.apache.coyote.http11.Http11NioProtocol"

• Jira behind a reverse-proxy
  If hosting Jira behind a reverse-proxy, such as Apache, please see Integrating Jira with Apache using SSL for more information.
  
  
• Adding new connections
  When you add a new connection, like an SSL one, the Jira config tool saves an entry with connection details in the server.xml file. This entry doesn't include properties that handle special characters, so you'll need to add them manually. This is required, as Jira won't work properly without it. We've described the required steps below, but you can read more about it here.
  
  
•  Insecure BKS-V1 keystore format
  Due to a security vulnerability of the BKS-V1 keystore format (provided by the BouncyCastle library), we recommend that you don't use it in your Jira instance. Learn more
  

Generate the Java KeyStore

In this section, you will create a Java Key Store (JKS), which will hold your SSL certificates. The SSL certificates are required for SSL to work in Jira. In the SSL world, certificates fall into two major categories:

Digital Certificates that are issued by trusted 3rd party CAs (Certification Authority) provide verification that your Website does indeed represent your company, thereby verifying your company's identity. Many CAs simply verify the domain name and issue the certificate. Other CAs, such as VeriSign, verify the existence of your business, the ownership of your domain name, and your authority to apply for the certificate, providing a higher standard of authentication.

A list of CA's can be found here. Some of the most well known CAs are:

• Verisign
• Thawte
• CAcert (relatively new CA, providing free CA certificates)

We recommend using a CA-signed certificate.

1. Download and install the Portecle app onto the server that runs Jira.
    This is a third-party application and is not supported by Atlassian.

2. Run the App as an Administrator, so it will have the appropriate permissions. Also, ensure the <JAVA_HOME> variable is pointing to the same version of Java that Jira uses. See Setting JAVA_HOME for further information on this.
    If running on a Linux/UNIX server, X11 will need to be forwarded when connecting to the server (so you can use the GUI), as below:

   ssh -X user@server

3. Select the Create a new Keystore option:
   
4. Select the type JKS and OK:
   
5. Select the Generate Key Pair button:
   
6. Select the RSA algorithm and a Key Size of 2048:
   
7. Make sure the Signature Algorithm is "SHA256withRSA" and refer to: Security tools report the default SSL Ciphers are too weak.
8.  Edit the certificate details, as per the below example and select OK:
   
    The Common Name MUST match the server's URL, otherwise errors will be displayed in the browser.
9. Choose an alias for the certificate - for example jira.
10. Enter a password for the KeyStore (the default password used is typically changeit).
11. The Key Pair Generation will report as successful, as per the below example:
    

12. Save the KeyStore in <Jira_HOME>/jira.jks, ensuring the use the same password in step 11. This can be done by File > Save Keystore.

    If using a self-signed certificate certificate, proceed to Configuring your web server using the Jira configuration tool. Otherwise, continue on.

13. We need to generate a Certificate Signing Request for the CA to sign and confirm the identity of the certificate. To do so, right click on the certificate and choose Generate CSR. Save it in <Jira_HOME>/jira.csr.
    
14. Submit the CSR to a Certificate Authority for signing. They will provide a signed certificate (CA reply) and a set of root/intermediate CA certificates.
15. Import the root and/or intermediate CA certificates with Import Trusted Certificate, repeating this step for each certificate.
    
16. Import the signed certificate by right clicking on the jira certificate and selecting Import CA Reply:
    
17. Select the certificate provided by the CA, which should be jira.crt. This will respond with CA Reply Import successful.
18. Verify this by checking Tools > Keystore Report. It should display the certificate as a child of the root certificates.
19. Save the KeyStore and proceed to the next section.

Configuring your web server using the Jira configuration tool

In this section, you will finish setting up SSL encryption for Jira, by configuring your web server using the Jira configuration tool. For more information on the Jira configuration tool, see Using the Jira configuration tool.

1. Run the Jira configuration tool, as follows:
   
   • Windows: Open a command prompt and run config.bat in the bin sub-directory of the Jira installation directory.
   • Linux/Unix: Open a console and execute config.sh in the bin sub-directory of the Jira installation directory.
      This may fail with the error as described in our Unable to Start Jira applications Config Tool due to No X11 DISPLAY variable was set error KB article. Please refer to it for the workaround.
2. Click the Web Server tab.
   Screenshot: Jira configuration tool — 'Web Server' tab
   

3. Fill out the fields as follows:

   Field	Value
   Control Port	Leave as default. You can change the port number if you wish. See Changing Jira's TCP ports .
   Profile	A profile is a preset web server configuration. You can pick from the four following values: Disabled HTTP only  HTTP & HTTPS (redirect HTTP to HTTPS) HTTPS only To run Jira over HTTPS, you must pick either 'HTTP & HTTPS' or 'HTTPS'. Pick 'HTTP & HTTPS' if you want to run Jira over HTTPS but you have users that access Jira via HTTP. If you pick 'HTTP & HTTPS', users who try to access Jira via HTTP will be redirected to the HTTPS address.
   HTTP port	Leave as default (8080). You can change the port number if you wish. See Changing Jira's TCP ports . This will be disabled if you set the Profile to 'HTTPS only'.
   HTTPS port	Leave as default (8443). You can change the port number if you wish. See Changing Jira's TCP ports .
   Keystore path	Specify the location of the keystore of your certificate. This will have been chosen when the keystore was saved in step 13 and should be <Jira_HOME>/jira.jks.
   Keystore password	Specify the password for your keystore. If you generated a self-signed certificate, this is the password you specified for the key and keystore when generating the certificate in step 13.
   Keystore alias	Each entry in the keystore is identified by an alias. We recommend using jira for this certificate as in step 10.

4. Click the Check Certificate in Key Store button to validate the following:
   
   • Test whether the certificate can be found in the key store.
   • Test whether keystore password works.
   • Test whether key can be found using key alias.
5. Click the Save button to save your changes.
6. Important: When adding a new connection, the config tool doesn’t include properties that allow special characters, so you’ll need to add them manually to the server.xml file. For more info on how to do this, see this kb article.

Advanced configuration

Running more than one instance on the same host

When running more than one instance on the same host, it is important to specify the address attribute in the <Jira_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 in The HTTP Connector Apache Tomcat docs.

Command Line Installation

Step 1. Create the KeyStore

1. Generate the Java KeyStore:

   <JAVA_HOME>/keytool -genkey -alias jira -keyalg RSA -keystore <Jira_HOME>/jira.jks

   Instead of first and last name, enter the server URL, excluding "https://" (e.g.: jira.atlassian.com).

2. Enter a password.

3. Create the CSR for signing, using the password from step 2:

   <JAVA_HOME>/keytool -certreq -alias jira -file /output/directory/csr.txt -keystore <Jira_HOME>/jira.jks

4. Submit the CSR to the CA for signing. They will provide a signed certificate and a root and/or intermediate CA.
    If the certificate will not be signed, skip to step 7.

5. Import the root and/or intermediate CA:

   <JAVA_HOME>/keytool -import -alias rootCA -keystore <Jira_HOME>/jira.jks -trustcacerts -file root.crt

6. Import the signed certificate (the CA provides this):

   <JAVA_HOME>/keytool -import -alias jira -keystore <Jira_HOME>/jira.jks -file jira.crt

7. Verify the certificate exists within the KeyStore:

   <JAVA_HOME>/keytool -list -alias jira -keystore <Jira_HOME>/jira.jks

   This must be a PrivateKeyEntry, if it is not the certificate setup has not successfully completed. For example:

   jira, Jan 1, 1970, PrivateKeyEntry,
   Certificate fingerprint (MD5): 73:68:CF:90:A8:1D:90:5B:CE:2A:2F:29:21:C6:B8:25

Step 2. Update Tomcat with the KeyStore

1. Create a backup of <Jira_INSTALL>/conf/server.xml before editing it.

2. Edit the HTTPS connector so that it has the parameters that point to the KeyStore:

   <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
                 maxHttpHeaderSize="8192" SSLEnabled="true"
                 maxThreads="150" minSpareThreads="25"
                 enableLookups="false" disableUploadTimeout="true"
                 acceptCount="100" scheme="https" secure="true"
                 sslEnabledProtocols="TLSv1.2,TLSv1.3"
                 clientAuth="false" useBodyEncodingForURI="true"
                 keyAlias="jira" keystoreFile="<Jira_HOME>/jira.jks" keystorePass="changeit" keystoreType="JKS"/>

    Ensure to put the appropriate path in place of <Jira_HOME> and change the port as needed.

   If the organization doesn't support the latest TLS version, you can fallback to an earlier version. Change:

   sslEnabledProtocols="TLSv1.2,TLSv1.3"

   To:

   sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2,TLSv1.3"

3. Edit the HTTP connector so that it redirects to the HTTPS connector:

   <Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" port="8080" protocol="HTTP/1.1" redirectPort="<PORT_FROM_STEP_1>" useBodyEncodingForURI="true"/>

    Ensure the <PORT_FROM_STEP_1> is change to the appropriate value. In this example it would be 8443.

4. Save the changes to server.xml.

5. If redirection to HTTPS will be used (this is recommended), edit the <Jira_INSTALL>/WEB-INF/web.xml file and add the following section at the end of the file, before the closing </web-app>. In this example, all URLs except attachments are redirected from HTTP to HTTPS.

   <security-constraint>
   	<web-resource-collection>
   		<web-resource-name>all-except-attachments</web-resource-name>
   		<url-pattern>*.jsp</url-pattern>
   		<url-pattern>*.jspa</url-pattern>
   		<url-pattern>/browse/*</url-pattern>
   		<url-pattern>/issues/*</url-pattern>
   	</web-resource-collection>
   	<user-data-constraint>
   		<transport-guarantee>CONFIDENTIAL</transport-guarantee>
   	</user-data-constraint>
   </security-constraint>

6. Restart Jira after you have saved your changes.

You can also redirect users from HTTP URLs to HTTPS URLs by choosing the 'HTTP & HTTPS' profile in the Jira configuration tool. This will redirect all HTTP URLs to HTTPS URLs.

If you want to only redirect certain pages to HTTPS, you need to do this manually. To do this, select the 'HTTPS only' profile in the Jira configuration tool and save the configuration, and then create an htaccess file on your web server that will manually redirect the HTTP URLs to the corresponding HTTPS URLs.

Troubleshooting

Here are some troubleshooting tips if you are using a self-signed key created by Portecle, as described above.

When you enter "https://localhost:<port number>" in your browser, if you get a message such as "Cannot establish a connection to the server at localhost:8443", look for error messages in your logs/catalina.out log file. Here are some possible errors with explanations.