Setting up SSL

By default, Jira runs with a standard non-encrypted HTTP protocol. This is acceptable if you are running Jira in a secure environment, such as an internal network. However, if you plan to open up access to Jira over the internet, you need to tighten up security by encrypting sensitive data, such as the usernames and passwords that are sent, by enabling HTTP over SSL (HTTPS).

This recipe describes how to install SSL on the Jira Tomcat application server. If you have an HTTP web server such as Apache in front of Jira, you can install the SSL certificate on the web server instead.

Getting ready

You need to have the following set up before you can step through this recipe:

1. Obtain a valid SSL certificate: You can either use a self-signed certificate or obtain one from a certificate authority (CA) such as Verisign. Using a self-signed certificate will display a warning message when users first visit the site, as shown in the following screenshot:

2. Ensure that the JAVA_HOME environment variable is set properly.
3. Make sure you know which JDK/JRE Jira is using. You can find this information from the System Info page in Jira, where you need to look for the java.home property.
4. Make sure your JRE/JDK's bin directory is added to your PATH environment variable, and the keytool command will output its usage, as shown in the following screenshot:

Now let's get started with the steps for this recipe.

How to do it...

Perform the following steps to import an SSL certificate:

1. Open up a command window and go to the directory where the certificate file resides.
2. Generate a Java KeyStore (JKS) for Jira by running the keytool -genkey -alias jira -keyalg RSA -keystore $JIRA_HOME/jira.jks command.
3. Import the certificate into the KeyStore repository by running the keytool -import -alias jira -keystore $JIRA_HOME/jira.jks -file file.crt command, where file.crt is the certificate file.
4. Open the server.xml file located in the JIRA_INSTALL/conf directory in a text editor.

5. Locate and uncomment the following XML configuration snippet:

<Connector port="8443" 
maxHttpHeaderSize="8192" SSLEnabled="true" 
maxThreads="150" 
minSpareThreads="25" maxSpareThreads="75" 
enableLookups="false"
disableUploadTimeout="true" 
acceptCount="100" scheme="https" secure="true" 
clientAuth="false" 
sslProtocol="TLS" useBodyEncodingForURI="true"/>

6. Add a few new attributes to the Connector tag and save the file, as follows:

keystoreFile="PATH_TO_YOUR_KEYSTORE" 
keystorePass="PASSWORD_FOR_YOUR_KEYSTORE" 
keyAlias="jira" 
keystoreType="JKS" 

7. Restart Jira to apply the changes.

How it works...

We first created a new Java KeyStore repository for Jira to store its own SSL certificate with Java's keytool utility. During this step, you are prompted to provide information about the store as well as a password to access the KeyStore repository.

Do not lose the password to the KeyStore repository.

After we created the KeyStore repository, we imported the certificate (and then enabled an additional connector to listen for HTTPS connections) by uncommenting the connector XML tag. We also added new attributes to the tag so that Tomcat knows where our new KeyStore repository is and how to access it to get to the certificate.

You can also change the port number for the connector if you want to run HTTPS on a more common port, 443, instead of the default port, 8443, and your final XML snippet will look something similar to the following:

<Connector port="443"
maxHttpHeaderSize="8192" SSLEnabled="true" maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100"
scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" useBodyEncodingForURI="true"
keystoreFile="/opt/jira/jira.jks" 
keystorePass="changeme"
keyAlias="jira" keystoreType="JKS"/>

There's more...

At this point, users can access Jira with both HTTP and HTTPS, and you need to configure Jira so that it will automatically redirect all HTTP traffic to HTTPS. Jira comes with a handy configuration utility that can help you set up this configuration.

You should first make sure your HTTPS configuration is working correctly before attempting this recipe.

Perform the following steps:

1. Open the Command Prompt and go to the JIRA_INSTALL/bin directory.
2. Depending on your OS, run the config.bat (Windows) or config.sh (Linux / OS X) file.
3. Select the Web Server tab from the JIRA Configuration Tool window.
4. Select the HTTP and HTTPs (redirect HTTP to HTTPs) option for Profile.
5. Click on the Save button at the bottom of the window, as shown in the following screenshot.

6. Restart Jira to apply the change:

If you cannot use the JIRA Configuration Tool, you can perform the following steps to set up the configuration manually:

1. Open the web.xml file located in the JIRA_INSTALL/atlassian-jira/WEB-INF directory.
2. Add the following XML snippet at the end of the file just before the closing </webapp> tag:

<security-constraint> 
 <display-name>HTTP to HTTPs Redirection</display-name> 
<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> 
</web-resource-collection> 
<user-data-constraint> 
 <transport-guarantee>CONFIDENTIAL</transport-guarantee> 
 </user-data-constraint> 
</security-constraint> 

3. Restart Jira to apply the change.

See also

For information on connecting Jira to other applications that run on SSL, refer to the next recipe.