Administering Jira applications Support

You can use SSL with Atlassian applications. However, SSL configuration is outside the scope of Atlassian Support. Still, here's what we can recommend:

If you need help with converting certificates, consult with the Atlassian partner who provided the certificate.
If you need help with configuring SSL, create a question in the Atlassian Community.

Be aware that SHA-1 is being phased out due to known weaknesses.

This article describes 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's not a definitive or comprehensive guide to configure HTTPS and may not apply to your environment.

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

Why should you run Jira over SSL or HTTPS? When people access web applications, there's always a possibility that their usernames and passwords can be intercepted by intermediaries between your computer and the ISP (Internet Service Provider) 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.

Running Jira without HTTPS enabled may leave your instance exposed to vulnerabilities, such as Man in the middle or DNS Rebinding attacks. We recommend that you enable HTTPS on your instance.

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, 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 configuration 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 the issue 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

Learn how to create a Java KeyStore (JKS) that 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:

Certificate	Description	When to use	Steps
Self-signed	These are certificates that haven't been digitally signed by a CA. This is a method of confirming the identity of the certificate that is being served by the web server. They are signed by themselves, hence the name "self-signed".	Test, developer, or internal servers only	1-13
CA-signed	A certificate that has had its identity digitally signed by a Certificate Authority (CA). This will allow browsers and clients to trust the certificate.	Production servers	1-19

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.

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

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

We recommend using a CA-signed certificate.

If you're unable to install Portecle on the server or prefer the command line, see our Command Line Installation section below.

Download and install the Portecle app onto the server that runs Jira.

This is a third-party application and isn't supported by Atlassian.
Run the app as an Admin, so it'll have 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.
If running on a Linux/UNIX server, X11 should be forwarded when connecting to the server so that you can use the GUI, as follows:
```
ssh -X user@server
```
Select Create a new Keystore.
Select the JKS type and select OK.
Select Generate Key Pair.
Select the RSA algorithm and the key size of 2048.
Make sure the Signature Algorithm is "SHA256withRSA" and refer to Security tools report the default SSL Ciphers are too weak.
Edit the certificate details as shown in the following example. Select OK.

The Common Name must match the server's URL. Otherwise errors will be displayed in the browser.
Choose an alias for the certificate. For example, jira.
Enter a password for the keystore. The default password used is typically changeit.
The Key Pair Generation will report as successful.
Save the keystore in <Jira_HOME>/jira.jks, ensuring that the same password as in the previous step is used. Do it by selecting File > Save Keystore.

If using a self-signed certificate certificate, proceed to Configuring your web server using the Jira configuration tool. Otherwise, go on.
You should generate a Certificate Signing Request for the CA to sign and confirm the identity of the certificate. To do so, right-click the certificate and choose Generate CSR. Save it in <Jira_HOME>/jira.csr.
Submit the CSR to the CA for signing. They'll provide a signed certificate (CA reply) and a set of root or intermediate CA certificates.
Import the root or intermediate CA certificates with Import Trusted Certificate, repeating this step for each certificate.
Import the signed certificate by right-clicking the jira certificate and selecting Import CA Reply.
Select the certificate provided by the CA. It should be jira.crt. You should receive the notification about the successful CA reply import.
Verify this by checking Tools > Keystore Report. It should display the certificate as a child of the root certificates.
Save the keystore and proceed to the next section.

Configuring your web server using the Jira configuration tool

Learn how to finish setting up the SSL encryption for Jira by configuring your web server with the Jira configuration tool. For more information on the Jira configuration tool, see Using the Jira configuration tool.

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 command might fail with the error as described in Unable to Start Jira applications Config Tool due to No X11 DISPLAY variable was set error. If it happens, refer to this article for the workaround.
Select Web Server.
Screenshot: Jira configuration tool—Web Server tab

Fill out the fields as follows:

Field	Value
Control Port	Leave as default. You can change the port number if you want. For more information, see Changing Jira's TCP ports.
Profile	A profile is a pre-set web server configuration. You can choose from the four following values: Disabled HTTP only HTTP & HTTPS (redirect HTTP to HTTPS) HTTPS only To run Jira over HTTPS, you should select either HTTP & HTTPS or HTTPS. Select HTTP & HTTPS if you want to run Jira over HTTPS but have users that access Jira via HTTP. In this case, 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 want. For more information, see Changing Jira's TCP ports. This field 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 want. For more information, see Changing Jira's TCP ports.
Keystore path	Specify the location of the keystore of your certificate. The location was generated when you saved the KeyStore 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 you generated and saved the certificate.
Keystore alias	Each entry in the keystore is identified by an alias. We recommend using `jira` for the certificate.

Select Check Certificate in Key Store to validate the following:
- Test whether the certificate can be found in the keystore.
- Test whether the keystore password works.
- Test whether the key can be found by using the key alias.
Save your changes.

When adding a new connection, the configuration tool doesn’t include properties that allow special characters. So, you’ll need to add them manually to the server.xml file. For more information on how to do this, see this article.

Advanced configuration

Running more than one instance on the same host

When running more than one instance on the same host, you should specify the address attribute in the <Jira_INSTALLATION>/conf/server.xml file. By default, the connector listens on all available network interfaces, so specifying the address will prevent conflicts with connectors running on the same default port. See more information on setting the address attribute in The HTTP Connector Apache Tomcat docs.

Command line installation

Step 1. Create the KeyStore

Generate the Java KeyStore.
```
<JAVA_HOME>/keytool -genkey -alias jira -keyalg RSA -keystore <Jira_HOME>/jira.jks
```
Instead of the first and last names, enter the server URL, excluding https://. For example: jira.atlassian.com.
Enter a password.

Create the CSR for signing and the password from the step 2.

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

Submit the CSR to the CA for signing. They'll provide a signed certificate and a root or intermediate CA.

If the certificate isn't signed, skip to Update Tomcat with the KeyStore.

Import the root or intermediate CA.

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

Import the signed certificate provided by the CA.

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

Verify if the certificate exists within the keystore.

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

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

Step 2. Update Tomcat with the KeyStore

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

Edit the HTTPS connector so that it has the parameters that point to the keystore:

<Connector relaxedPathChars="[]|" 
relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" 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"/>

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

If your organization doesn't support the latest TLS version, you can fall back to an earlier version. To do this, change:

sslEnabledProtocols="TLSv1.2,TLSv1.3"

to

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

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

<Connector relaxedPathChars="[]|" 
relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" 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 that the <PORT_FROM_STEP_1> is changed to the appropriate value. In this example, it's 8443.

Save the changes to server.xml.

If redirection to HTTPS is used, which 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>

Save your changes and restart Jira.

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

If you want to only redirect certain pages to HTTPS, you should this manually.

Select the HTTPS only profile in the Jira configuration tool and save the configuration.
Create an htaccess file on your web server that will 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 and get a message like "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.

Click to see possible errors and solutions for them

SSL + Apache + IE problems: errors may occur when you upload attachments over SSL using IE. This is due to an IE bug and can be fixed in Apache by setting:
```
BrowserMatch ".MSIE." \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
```
Google offers a clarification for this.
Can't find the keystore
```
java.io.FileNotFoundException: /home/user/.keystore (No such file or directory)
```
This indicates that Tomcat can't find the keystore. The keytool utility creates the keystore as the.keystore file in the current user's home directory. For Unix/Linux, the home directory should be /home/<username>. For Windows. it should be C:\Documents And Settings\<UserName>.
Make sure you're running Jira as the same user who's created the keystore. If not or if you're running Jira on Windows as a service, you should specify where the keystore file is in conf/server.xml. Add the following attribute to the connector tag you uncommented:
```
keystoreFile="<location of keystore file>"
```
This error may also occur if you add the keystoreFile attribute to the http connector in server.xml instead of the https connector.
Certificate reply and certificate in keystore are identical
```
keytool error: java.lang.Exception: Certificate reply and certificate in keystore are identical
```
This error will occur if you have identical names or fingerprints. This happens when you try to recreate the certificate in the existing keystore. If you need to recreate or update the certificate, remove the existing keystore and create a new one. In this case, creating a new keystore and adding the related certificates will fix the issue. The default path for it is $JAVA_HOME/jre/lib/security/cacerts.
Incorrect password
```
java.io.IOException: Keystore was tampered with, or password was incorrect
```
You might use a different password than changeit. You should use changeit for both the keystore password and for the Tomcat key password. Or if you want to use a different password, you should it by using the keystorePass attribute of the Connector tag, as described above.
Passwords don't match
```
java.io.IOException: Cannot recover key
```
You specified a different value for the keystore password and the Tomcat key password. Both passwords must be the same.

Wrong certificate

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 SSL Connector in conf/server.xml.

Add the keyAlias attribute with a relevant alias to the Connector tag you uncommented. For example:

<Connector relaxedPathChars="[]|" 
relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true" useBodyEncodingForURI="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="/opt/local/.keystore"
keystorePass="removed"
keyAlias="tomcat"/>

Using Apache Portable Runtime

APR uses a different SSL engine. So, you'll see an exception like this in your logs:

SEVERE: Failed to initialize connector [Connector[HTTP/1.1-8443]]
LifecycleException:  Protocol handler initialization failed: java.lang.Exception: No Certificate file specified or invalid file format

The reason for this is that the APR Connector uses OpenSSL and can't use the keystore in the same way. You can rectify this in one of the following ways:

Use Http11NioProtocol to handle SSL connections. Edit server.xml so that the SSL Connector tag you uncommented specifies Http11NioProtocol instead of the APR protocol.

<Connector relaxedPathChars="[]|" 
relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
  maxHttpHeaderSize="8192" SSLEnabled="true" keystoreFile="${user.home}/.keystore"
  maxThreads="150" enableLookups="false" disableUploadTimeout="true"
  acceptCount="100" scheme="https" secure="true"
  clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"/>

Or configure the Connector to use the APR protocol. You can do it only if you have PEM encoded certificates and private keys. If you've used OpenSSL to generate your key, you'll have these PEM encoded files. In all other cases, contact your certificate provider for assistance.

<Connector relaxedPathChars="[]|" 
relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"   port="8443" maxThreads="200"
  scheme="https" secure="true" SSLEnabled="true"
  SSLCertificateFile="${user.home}/certificate.pem"
  SSLCertificateKeyFile="${user.home}/key.pem"
  clientAuth="optional" SSLProtocol="TLSv1.2,TLSv1.3"/>

Enabling Client Authentication: to enable client authentication in Tomcat, ensure that the value of the clientAuth attribute in the Connector element of Tomcat's server.xml file is true.
```
<Connector 
	...
	clientAuth="true"
	... />
```
For more information about the Connector element parameters, please refer to the SSL Configuration HOW-TO Tomcat 8 documentation.

Administering Jira applications Support

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

Suggestions and bugs

Marketplace

Billing and licensing

Running Jira applications over SSL or HTTPS

System administration

On this page

Still need help?

Before you begin

Support

Windows installers

Related bugs

Jira behind a reverse-proxy

Adding new connections

Insecure BKS-V1 keystore format

Configuring your web server using the Jira configuration tool

Running more than one instance on the same host

Command line installation

Step 1. Create the KeyStore

Step 2. Update Tomcat with the KeyStore

Troubleshooting

Page

Viewport

Confluence

Versions

Running Jira applications over SSL or HTTPS

System administration

On this page

Related content

Still need help?

Before you begin

Support

Windows installers

Related bugs

Jira behind a reverse-proxy

Adding new connections

Insecure BKS-V1 keystore format

Configuring your web server using the Jira configuration tool

Running more than one instance on the same host

Command line installation

Step 1. Create the KeyStore

Step 2. Update Tomcat with the KeyStore

Troubleshooting

Related content