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 being 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 in the web server instead.
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_HOMEenvironment variable is set properly.Make sure you know which JDK/JRE JIRA is using. You can find this information from the System Info page, where you need to look for the
java.homeproperty.Make sure your JRE/JDK's
bindirectory is added to your PATH environment variable, and thekeytoolcommand will output its usage, as shown in the following screenshot:
Perform the following steps to import an SSL certificate:
Open up a command window and go to the directory where the certificate file resides.
Generate a Java KeyStore (JKS) for JIRA by running the
keytool -genkey -alias jira -keyalg RSA -keystore JIRA_INSTALL/jira.jkscommand.Import the certificate into KeyStore by running the
keytool –import –alias jira –keystore JIRA_INSTALL/jira.jks –file file.crtcommand, wherefile.crtis the certificate file.Open the
server.xmlfile located in theJIRA_INSTALL/confdirectory in a text editor.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"/>
Note
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
Add a few new attributes to the
Connectortag and save the file:keystoreFile="PATH_TO_YOUR_KEYSTORE" keystorePass="PASSWORD_FOR_YOUR_KEYSTORE" keyAlias="jira" keystoreType="JKS"
We first created a new Java KeyStore 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 KeyStore.
After we created KeyStore, 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 will know where our new KeyStore 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 8443, and your final XML snippet will look something like 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"/>
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.
Tip
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:
Open the command prompt and go to the
JIRA_INSTALL/bindirectory.Depending on your OS, run the
config.batorconfig.shfile.Select the Web Server tab from the JIRA Configuration Tool window.
Select the HTTP and HTTPs (redirect HTTP to HTTPs) option for Profile.
Click on the Save button at the bottom of the window as shown in the following screenshot.
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:
Open the
web.xmlfile located in theJIRA_INSTALL/atlassian-jira/WEB-INFdirectory.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>