When web applications are being accessed across the internet, there is always the possibility of usernames and passwords being intercepted by intermediaries between your computer and the ISP/company. It is often 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. In some cases where issue data is sensitive, all pages should be accessed via HTTPS.
 | Please note that Atlassian Support will refer SSL support to the institution that issues the Certificate. We provide this documentation for reference. |
The process of enabling SSL access is specific to each application server, but the process for specifying which pages require protection is generic.
| This procedure is a general guide for the way to configure Tomcat with HTTPS and only covers the common installation types of JIRA. It is by no means a definitive or comprehensive guide to configuring HTTPS and may not be applicable to your specific integration. |
 | For JIRA Windows Standalone installations
|
On this page:
Running JIRA over HTTPS
The following flowchart shows the process involved in configuring HTTPS on Tomcat. Click the links below this chart to go to the instructions for that step.
- Configure HTTPS in Tomcat
- Generate Self-Signed Certificate
- Obtain CA Certificate
- Import Certificate into the Trust-store
- Requiring HTTPS for certain pages (Redirecting certain pages to HTTPS)
Configure HTTPS in Tomcat
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:
<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" />
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).
Generate Self-Signed Certificate
| Self-signed certificates are useful in cases where you require encryption but do not need to verify the website identity. They are commonly used for testing and on internal corporate networks (intranets). Due to the certificate not being signed by a Certification Authority (CA), users may get prompted that the site is untrusted and may have to perform several steps to "accept" the certificate before they can access the site. This usually will only occur the first time they access the site. |
The following approach to create the certificate uses Java's keytool, and has been formatted for use with Java 1.6.
There are other tools for generating certificates such as openSSL which are not discussed in this procedure.
| When running the following keytool command you will be prompted with:
What is your first and last name? Instead of entering your first and last name as specified, you must enter the fully qualified hostname of the server running JIRA. This is the same as the name you would type in your web browser after the http:// section to access your JIRA installation. When the client web browser examines the certificate, it checks this field, and makes sure that it matches the hostname. If it doesn't, it may prevent access to the site, and at the very least will generate pop-up messages saying that there is a mismatch. An example of a qualified hostname is: support.atlassian.com
|
Windows Standalone
"<install_dir>\jre\bin\keytool" -genkey -alias tomcat -keyalg RSA
Windows WAR/EAR
"%JAVA_HOME\bin\keytool" -genkey -alias tomcat -keyalg RSA
Unix/Linux
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
This will create (if it doesn't already exist) a new .keystore file located in the home directory of the user you used to run the keytool command.
You will now need to export the certificate to make it ready for importing into the Trust-store with the following command:
Windows Standalone
"<install_dir>\jre\bin\keytool" -export -alias tomcat -file file.cer
Windows WAR/EAR
"%JAVA_HOME\bin\keytool" -export -alias tomcat -file file.cer
Unix/Linux
$JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer
Next, import the certificate into the Trust-store.
Obtain CA Certificate
Digital Certificate that are issued by trusted 3rd party CAs (Certification Authority) provide verification that your Website does indeed represent your company, thereby verifying your company's identity. Many CAs simply verify the domain name and issue the certificate, whereas other such as VeriSign verifies 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 CA's can be found here.
Some of the most well known CAs are:
Next, import the certificate into the Trust-store.
Import Certificate into the Trust-store
Assuming your certificate is called "file.cer" whether obtained by a CA or self-generated, the following command will add this certificate to the Trust-store:
Windows Standalone
"<install_dir>\jre\bin\keytool" -import -alias tomcat -file file.cer -keystore "<install_dir>\jre\lib\security\cacerts"
Windows WAR/EAR
"%JAVA_HOME\bin\keytool" -import -alias tomcat -file file.cer -keystore "%JAVA_HOME%\jre\lib\security\cacerts"
Unix/Linux
| This step must be performed as the root user, or with the use of sudo |
$JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer -keystore $JAVA_HOME/jre/lib/security/cacerts
Next, proceed to the step on redirecting certain pages to HTTPS.
Redirecting certain pages to HTTPS
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. The port it redirects to is determined by the redirectPort value you specify in the server.xml file in the HTTP Connector stanza.
There does not seem to be an easy way to make subsequent pages revert to HTTP after logging in via HTTPS - see JRA-7250
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:
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.
Can't find the keystore
java.io.FileNotFoundException: /home/user/.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 running 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="/opt/local/.keystore" keystorePass="removed" keyAlias="tomcat"/>
Comments (14)
Jan 03, 2006
f says:
If you have a signed x509 for your URL already, there is no easy one step method...If you have a signed x509 for your URL already, there is no easy one step method to import the key and the cert to Java/Tomcat. The problem arises in the way Java's keystore uses PKS mode for keys, where as Apache and X509 stores keys in PEM mode. (Sorry, I can't give you a more techincal explanation).
If you import the wrong key type the error message you will get from mozilla is:
"Mozilla and localhost cannot communicate securely because they have no common encryption algorithms".
IE will display a window with only a few squares but no error message.
The fix for this can be found here: http://mail-archives.apache.org/mod_mbox/jakarta-tomcat-user/200408.mbox/%3C20040805090009.75478.qmail@web12308.mail.yahoo.com%3E
This is geared towards older Tomcat 4.1 and uses a free 3rd party tool.
May 23, 2006
Tracy Rager says:
We are using Jira 3.5 with Tomcat 5.5, and have it starting as a servi...We are using Jira 3.5 with Tomcat 5.5, and have it starting as a service within Windows. I made the changes above to add HTTPS, using a self-signed cert for now, and restarted the service. It still works for port 8080, but 8443 only works if I stop the service and start it using the startup.bat command. Any suggestions?
Thanks,
tracy
May 30, 2006
Brian Nguyen says:
Hi Tracy, Sorry about the late reply. The problem here is that the Tomcat serve...Hi Tracy,
Sorry about the late reply. The problem here is that the Tomcat server is looking for the keystore file in the user's home directory (Documents And Settings/<UserName>). However the Windows Service starts Tomcat using the System account not your user account, this then means Tomcat can't find the file.
So in order to get this to work on Windows you will need to explicitly set the location of the keystore file. To do this:
1. Find the .keystore file in your user directory, copy its location
2. Open conf/server.xml
3. In the connector tag that you uncommented add the parameter:
keystoreFile="<location of keystore file>"
4. Restart Jira Service
Thanks,
Brian
Aug 25, 2006
nick watson says:
Hi, i have just finished installing tomcat 5.5.17 however when i am finished set...Hi, i have just finished installing tomcat 5.5.17 however when i am finished setting up my cert (no errors) i can only browse port 8443 over http not https (uncommented the ssl section in server.xml) also added a direct mapping to the keystore
Any ideas what could be wrong?
TIA
Nick
Aug 30, 2006
Jeff Turner says:
Double-check your server.xml. It sounds like you changed the HTTP connector from...Double-check your server.xml. It sounds like you changed the HTTP connector from 8080 to 8443.
Cheers,
Jeff
Jan 08, 2008
Owen Carter says:
Really minor point.. It would be nice if the <security-constraint> section...Really minor point..
It would be nice if the <security-constraint> section for the web.xml file was added as a commented-out section in the supplied web.xml that comes with Jira.
Jun 10, 2008
Matthew Block says:
Okay, after fighting this for a good day, I finally got it working with my exist...Okay, after fighting this for a good day, I finally got it working with my existing ssl certificate. I have a *.<domain name> certificate with the cert and private keys in separate files. After several searches and trial and error, turns out you can just use the openssl tool to create a PKCS12 keystore which contains your private key and then tell JIRA to use that keystore. This site (https://wiki.systemsx.ch/display/ITDOC/Import+an+openssl+generated+key+into+a+tomcat+application) was the most help for me. But basically, here are the steps...
Mar 03, 2009
Anonymous says:
Two things that should be mentioned. I think this document could be improved it...Two things that should be mentioned.
I think this document could be improved it if explicitly named a keyfile path by default. Almost every setup out here will have Tomcat running under a system account (Win) or "tomcat" (Linux).
The self-signed certificate generated above will only be valid for 90 days by default. I used this command (expires in 10 years):
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -dname "cn=Stewart Vardaman, ou=STG, o=Echostar, c=US" -validity 3650
Mar 03, 2009
Anonymous says:
One more comment: I personally wouldn't keep my keystore file in "/home/ida...One more comment: I personally wouldn't keep my keystore file in "/home/idaniel/.keystore" -- say ldaniel leaves company and someone in IT removes his user dir. Next time Tomcat is restarted the SSL side will die.
Sep 09
Anonymous says:
For those running Windows, SSL certs are typically stored or archived in PFX fil...For those running Windows, SSL certs are typically stored or archived in PFX files. (Microsoft's PFX Keystore is PKCS#12 format and may alternatively have a .p12 file extension.)
I've found that there is no need for use of keytool or openssl to get JIRA / Tomcat to function using the Windows native PFX SSL archive files.
The secret is the use of the keystoreType attribute within the connector set to "PKCS12":
<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"
keystoreFile="C:\JIRA_.example.com.pfx"
keystorePass="*******"
keystoreType="PKCS12" />
After importing a cert, purchased from GoDaddy, into the Windows certificate repository (via MMC cert snap-in), I then exported the PFX cert backup. In this particular case, this was successfully setup with a wildcard domain cert.
Jonathan B.
Dec 03
Scott Geertgens says:
In JIRA 4.0+, it is still necessary to use the keytool to import your cert into ...In JIRA 4.0+, it is still necessary to use the keytool to import your cert into the JRE used by Jira 4.0 (typically in jira4.0\jre\lib\security\cacerts) keystore even when using .pfx files, in addition to the above server.xml changes. From my initial testing, it appears that can be done via the following:
Note that you are doing an -importkeystore because a .pfx file is itself a keystore, not just a plain cert.
Failing to do so will lead to the issue described here
Sep 25
Anonymous says:
Hi Radek here from MoneyMate. We're currently evaluating JIRA and CONFLUENCE - b...Hi Radek here from MoneyMate. We're currently evaluating JIRA and CONFLUENCE - both on UBUNTU Linux 64-bit connected to MySQL. HTTP and HTTPS access is working fine. My question is: is it there a possibility how to define a next HTTPS connector with a different certificate (on a different port of course)? What we want is to have two sites - for example https://jira.mm.com and https://jira.moneymate.com pointed to the same JIRA (or CONFLUENCE) installation with correct certificates. Can I duplicate HTTPS section in server.xml or ...? Any idea would be appreciated.
Nov 05
Anonymous says:
This documentation could be inproved, it is somewhat confusing. When asked to ...This documentation could be inproved, it is somewhat confusing.
Why on earth would I have to use the DNS name in place of 'first and last name'?
Nov 23
Anonymous says:
Why on earth would I have to use the DNS name in place of 'first and last ...Because that's the way how server certificates work. You should better educate yourself on the topic of server certificates.