In this post I’m going to show you how to setup SSL in JIRA with an existing SSL certificate.
If you setup SSL in JIRA from scratch by requesting a new certificate the official instructions work well but when you have an existing certificate the instructions are not very clear, especially to someone that is not familiar with Java and Tomcat. If you read further down in the comments and google a bit you can piece it together but I want to bring it all together in a single post to make it easier next time I have to do it. These instructions are for windows but should work for any OS since the tools used are ports from Linux anyway.
Tools
Before we start you’ll need a few things:
- If you want to know what .pem, pkcs12 and .key files are please read this first.
- Your SSL certificate, private key pair and the password that was used to create the private key. If you received it as text in a email instead of file attachments you can copy and paste them into separate files but remember to include the –begin***— and —end***– parts for the certificate and the private key. The extensions does not really matter when you run the tools but I named mine .key and .pem to make it easier.
- OpenSSL: You can download it from sourceforge.
- Jave JRE: You will have this one already since it is part of the JIRA installation in my case it was in C:\Program Files\Atlassian\JIRA\jre\bin\ and the tool you need is keytool.exe
Steps
Export your certificate to pkcs12, the format the Java key tool understands. You will find openssl in C:\Program Files (x86)\GnuWin32\bin, run openssl.exe to get the openssl command prompt then run:
pkcs12 -export -in c:\cert\your_ssl.pem -inkey c:\cert\your_keyfile.key -out newfile.p12 -name alias
The alias is optional and if you don’t provide one the tool will assign a number as the alias, starting from 1. If you want to see the alias for existing files have a look at the command line parameters for openssl. You will be prompted for the password used to generate the private key pair. If successful you will see the newfile.p12 created in the output folder.
Next step is to create the java key store, I called this one jira.jks.
"%java_home%\bin\keytool.exe" -importkeystore -srckeystore newfile.p12 -destkeystore jira.jks -srcstoretype pkcs12 -alias alias
You will be prompted to create a new password for this keystore and then you will be prompted for the private key password used to create the exported certificate. It is imported the use the private key password as the new password for this key store or else JIRA will complain, example of the error message below.
Now you can configure JIRA to use this Java keystore for SSL by running config.bat it is located in the bin folder of your JIRA installation.
If you want to have a look what is inside existing Java keystore certificates you can use openssl.exe to view them or you can use portecle if you prefer a GUI.
Side Note: To manually configure a Tomcat connector for SSL, edit <tomcat_dir>/conf/server/xml and add the following:
<Connector port="8443" maxThreads="150" scheme="https" secure="true" SSLEnabled="true" keystoreFile="path/to/your/keystore" keystorePass="YourKeystorePassword" clientAuth="false" keyAlias="alias" sslProtocol="TLS"/>
Tip: I had endless trouble creating application links between JIRA and BitBucket with SSL enabled. BitBucket was able to use the JIRA user directory but application links were throwing certificate errors and http 500 errors on the application links screen. In the end I had to change JIRA to use port 443 instead of 8443 and it solved the problem.
