Running JIRA over SSL or HTTPS

When web applications are being accessed across the internet, there is always the possibility of usernames and passwords being intercepted by intermediaries (e.g. between your computer and the ISP/company). It is often a good idea to enable access via HTTPS (HTTP over SSL), and require its use for pages where passwords are sent. Note, however, that using HTTPS may result in slower performance.

In some cases where issue data is sensitive, all pages should be accessed via HTTPS.
The process of enabling SSL access is specific to each app server, but specifying which pages to require protection for is generic. Here we describe the process for Tomcat, bundled with JIRA Standalone.

JIRA 3.5.3 has a bug which causes a popup warning to appear for IE users when using SSL. This has been fixed in 3.6 and above

Enable SSL access

Tomcat (JIRA Standalone)

Edit conf/server.xml, and at the bottom before the </Service> tag, add this section (or uncomment it where you find it) in Tomcat 5.5 (JIRA Standalone >= 3.3):

<Connector 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" />

or the following if using Tomcat 4.1.x (JIRA Standalone <= 3.2.3):

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true"
acceptCount="100" debug="0" scheme="https" secure="true"
useURIValidationHack="false" disableUploadTimeout="true">
<Factory className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
clientAuth="false" protocol="TLS" />
</Connector>

This enables SSL access on port 8443 (the default for https is 443, but just as Tomcat uses 8080 instead of 80 to avoid conflicts, 8443 is used instead of 443 here).

Now create a SSL key for Tomcat to send to connecting clients. You can create a self-signed key for testing purposes with one of the following commands:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA (Windows)
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA  (Unix)

The keytool utility will prompt you for two passwords: the keystore password and the key password for Tomcat. You must use the same value for both passwords, and the value must be either:

1. "changeit" (this is the default value Tomcat expects), or
2. if you use a value other than "changeit", you must also specify it in conf/server.xml. You must add the following attribute to the Connector tag described above:

   keystorePass="<password value>"
   

To add a CA-issued key pair, see the Tomcat documentation.

IE7 on Vista Issue If your clients will access JIRA from Internet Explorer 7 on Vista, please ensure that you specify the -keyalg RSA flag. By default the SHA1 algorithm is used, which results in 'Internet Explorer cannot display the webpage' errors on IE7 on Vista. Apparently on JDK 1.6 you also need to specify the -sigalg MD5withRSA flag since -keyalg RSA will still result in SHA1 being used (see this blog for more information).

Once Tomcat is restarted, you should be able to access JIRA on https://localhost:8443/. Try this before continuing.

Importing from a CA issued Certificate

When using CA certificates, you also need import the certificate using the keytool command, rather than generating a self-signed key. Something like the command below.

keytool -import -alias tomcat -file certificate.cer -keystore some/path/to/file -storepass something.secure

The -file is your certificate and the -keystore is an optional destination, but it'll guarantee that you know where your keystore is. By default, the keystore is placed in your user home directory. You can get more information on the keytool at the keytool documentation.

You'd then need to edit the server.xml as per the Tomcat Docs "Edit the Tomcat Configuration File" section. Basically, you'll need to add the keystoreFile and keystorePass to the SSL Connector definition to match your keystore settings.

Requiring HTTPS for certain pages

Although HTTPS is now activated and available, the old HTTP URLs (http://localhost:8080) are still available. In most situations one wants these URLs to continue working, but for some to redirect to their https equivalent. This is done by editing WEB-INF/web.xml, and adding the following section at the end of the file, before the closing </web-app>:

<security-constraint>
	<web-resource-collection>
		<web-resource-name>all-except-attachments</web-resource-name>
		<url-pattern>*.js</url-pattern>
		<url-pattern>*.jsp</url-pattern>
		<url-pattern>*.jspa</url-pattern>
		<url-pattern>*.css</url-pattern>
		<url-pattern>/browse/*</url-pattern>
	</web-resource-collection>
	<user-data-constraint>
		<transport-guarantee>CONFIDENTIAL</transport-guarantee>
	</user-data-constraint>
</security-constraint>

This means that all URLs except attachments are redirected from HTTP to HTTPS. IE has a bug which prevents attachments like .doc files being viewed via HTTPS if SSL protection is forced in web.xml.

Once this change is made, restart JIRA and access http://localhost:8080. You should be redirected to https://localhost:8443/secure/Dashboard.jspa.

(!)There does not seem to be an easy way to make subsequent pages revert to HTTP after logging in via HTTPS - see JRA-7250

SSL + Apache + IE problems

Some people have reported errors when uploading 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 has plenty more on this.

Troubleshooting

Here are some troubleshooting tips if you are using a self-signed key created by keytool, as described above.

When you enter "https://localhost:8443" in your browser, if you get a message such as "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:

Can't find the keystore

java.io.FileNotFoundException: /home/idaniel/.keystore (No such file or directory)

This indicates that Tomcat cannot find the keystore. The keytool utility creates the keystore as a file called .keystore in the current user's home directory. For Unix/Linux the home directory is likely to be /home/<username>. For Windows it is likely to be C:\Documents And Settings\<UserName>.

Make sure you are run JIRA as the same user who created the keystore. If this is not the case, or if you are running JIRA on Windows as a service, you will need to 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>"

Incorrect password

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

You used a different password than "changeit". You must either use "changeit" for both the keystore password and for the key password for Tomcat, or if you want to use a different password, you must specify it 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 key password for Tomcat. 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 unless otherwise specified in the SSL Connector in conf/server.xml.

Add the keyAlias attribute to the Connector tag you uncommented, with the relevant alias, for example:

   <Connector 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="/home/idaniel/.keystore"
              keystorePass="removed" 
              keyAlias="tomcat"/>