Setting up SSL

By default, JIRA runs with a standard nonencrypted HTTP protocol. This is acceptable if you are running JIRA in a secured environment, such as an internal network. However, if you plan to open up access to JIRA over the Internet, you need to tighten up the 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:

• 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:
  
• Ensure that the JAVA_HOME environment variable is set properly.
• 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.
• 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:
  

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_INSTALL/jira.jks command.
3. Import the certificate into KeyStore repository by running the keytool -import -alias jira -keystore JIRA_INSTALL/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 certificate as well as a password to access the KeyStore repository.

Note

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 the 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 the HTTP traffic to HTTPS. JIRA comes with a handy configuration utility that can help you set up this configuration.

Note

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

Note that this utility is only available for standalone installations. If you are running a WAR installation, you can skip the following steps and move on to the manual setup section:

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 JIRA Configuration Tool, you can perform the following steps to manually set up the configuration:

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 Installing SSL certificates from other applications recipe.