This article describes how to run Jira applications over SSL or HTTPS by configuring Apache Tomcat with HTTPS.

When should you run Jira over SSL or HTTPS? 

Running Jira without HTTPS enabled may leave your instance exposed to vulnerabilities, such as man-in-the-middle (MITM) or DNS rebinding attacks. We recommend enabling HTTPS on your instance.

We suggest offloading SSL traffic at your reverse proxy (load balancer), assuming the last-mile connection from the reverse proxy to Jira is through a secured intranet. This removes the cryptographic overhead from Jira Data Center, simplifying deployment/upgrades.

If your security posture requires end-to-end SSL encryption, or you don’t use a reverse proxy, follow the steps below to configure Apache Tomcat with SSL.

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.

Java installation

When updating SSL certificates, use keytool with the same JRE or JDK installation that is used by your Jira. To confirm this path:

1. Go to Setting , then System.
2. In the System Support section, select System info.
3. Go to the java.home line and verify the path.

Jira behind a reverse-proxy (load balancer)

If hosting Jira behind a reverse-proxy, such as Apache, see Integrating Jira with Apache using SSL for more information.

Prepare your SSL certificate

The SSL certificates fall into two major categories:

Digital Certificates that are issued by trusted third-party CAs provide verification that your website indeed represents 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.

For example, you can consult Apple and check the list of available root certificates. Some of the most well known CAs are:

• Verisign
• DigiCert

We recommend using a CA-signed certificate.

Creating keystore

 To create a keystore:

1. Prepare the following:

   1. cert.pem: your signed SSL certificate.

   2. privkey.pem: your SSL certificate’s private key

   3. (optional) chain.pem: root and intermediate certificate chain.

2. Generate the PKCS#12 store with the code below.
   

   Replace changeit with a unique password. Explore OpenSSL documentation about openssl-pkcs12

   
   

   openssl pkcs12 -export \
     -in /path/to/cert.pem \
     -inkey /path/to/privkey.pem \
     -certfile /path/to/chain.pem \
     -out <jira-local-home>/keystore.p12 \
     -name jira \
     -passout pass:changeit

3. Verify if the certificate exists within the keystore.
   

   <java-home>/bin/bin/keytool -list -alias jira -keystore <jira-local-home>/keystore.p12

   This must be a PrivateKeyEntry. If it isn't, the certificate setup hasn't been completed successfully. 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

   
   

Updating Tomcat with keystore 

To update Tomcat with the keystore:

1. Create a backup of <jira-install>/conf/server.xml before editing it.

2. Create a new HTTPS connector that points to the keystore. Make sure to update the path, password, and alias.
   

   <Connector port="8443"
              relaxedPathChars="[]|"
              relaxedQueryChars="[]|{}^\`"<>"
              maxThreads="150"
              minSpareThreads="25"
              connectionTimeout="20000"
              enableLookups="false"
              maxHttpHeaderSize="8192"
              useBodyEncodingForURI="true"
              acceptCount="100"
              disableUploadTimeout="true"
              bindOnInit="false"
              secure="true"
              scheme="https"
              protocol="org.apache.coyote.http11.Http11Nio2Protocol"
              SSLEnabled="true">
       <SSLHostConfig>
           <Certificate
                   certificateKeystoreFile="/var/atlassian/application-data/jira/keystore.p12"
                   certificateKeystorePassword="changeit"
                   certificateKeyAlias="jira"
           />
       </SSLHostConfig>
   </Connector>

   
   
3. If needed, update the HTTP connector’s redirectPort so that it redirects to the HTTPS connector.
   

   <Connector port="8080"
              relaxedPathChars="[]|"
              relaxedQueryChars="[]|{}^\`"<>"
              maxThreads="150"
              minSpareThreads="25"
              connectionTimeout="20000"
              enableLookups="false"
              maxHttpHeaderSize="8192"
              protocol="HTTP/1.1"
              useBodyEncodingForURI="true"
              redirectPort="8443"
              acceptCount="100"
              disableUploadTimeout="true"
              bindOnInit="false"
   />

    

4. Save the changes to server.xml.

5. Restart the Jira node.

Repeat these steps for any remaining nodes.

Further configuration

HTTPS redirection

If redirection to HTTPS is used, which is recommended, edit the <jira-install>/conf/web.xml file and add the following section at the end of the file, before the closing </web-app>. In the example below, 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>

Certificate validation

To require Tomcat to validate the certificate chain during startup, update <SSLHostConfig>. This replaces the obsolete clientAuth connector attribute in earlier Tomcat versions.

<SSLHostConfig
        caCertificateFile="/path/to/ca.pem"
        certificateVerification="require"
        certificateVerificationDepth="10">
    [...]
</SSLHostConfig>

Restricting protocols

By default, the following protocols are accepted:

• TLSv1

• TLSv1.1

• TLSv1.2

• TLSv1.3

• SSLv2Hello

To limit the accepted protocols or ciphers, refer directly to the protocols and ciphers attributes. More on Apache Tomcat 10 configuration

Troubleshooting

Incorrect password

If the password is incorrect, you can see the following error message:

java.io.IOException: Keystore was tampered with, or password was incorrect

java.io.IOException: Cannot recover key

You might use a different password than changeit. You should specify the same password when generating the PKCS#12 .p12 store and in the Tomcat server.xml file. Otherwise, you can see the following error messages:

Wrong certificate

If the certificate is incorrect, you can see the following error message:

javax.net.ssl.SSLException: No available certificate corresponds to the SSL cipher suites which are enabled.

If the keystore has more than one certificate, Tomcat will use the first returned one unless other is specified in the HTTPS connector in server.xml.

To solve this, add the certificateKeyAlias attribute with a relevant alias to the Certificate tag.

Obsolete format

If the format is obsolete, you can see the following error message:

Caused by: java.lang.IllegalArgumentException: no element SSLHostConfig found with hostName [_default_] corresponding to defaultSSLHostConfigName for the connector [https-jsse-nio-8443]

The deprecated connector SSL attributes, such as keystoreFile or keystorePass, were removed in Tomcat 10.1 (Jira 11.0 and later). Ensure that your HTTP (8080) and HTTPS (8443) connectors match the template above.

Additional resources

You can also find more information on the subject in the following articles:

• Integrating Jira with Apache using SSL

• How to import a public SSL certificate into a JVM