Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
HOWTO Configure Atlassian Jira to use Letsencrypt certificate

HOWTO Configure Atlassian Jira to use Letsencrypt certificate with default Tomcat

This is a primer for installing a Letsencrypt certificate on a Jira server that is running the Jira provided, default Tomcat for serving webpages.

I found lots of information about how to do it using a free-standing Tomcat or nginx, but nothing about this particular combination. I hope it helps you!

Obviously, in all the examples, you need to replace jira.example.com with your own domain! And (duh) you need to use your own password, not 1234

You need to have installed Java (outside the scope of this document). Then in your user's shell RC file and probably root's RC file, add

export JAVA_HOME=$(readlink -f /usr/bin/java | sed "s:bin/java::")

Jira should NOT be running while you're doing this.

Get Letsencrypt (certbot)


For CentOS/RHEL

$ wget https://dl.eff.org/certbot-auto
$ chmod a+x certbot-auto

For Ubuntu (16.04)

$ sudo apt-get update
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt-get update
$ sudo apt-get install certbot

Get your certificate


$ sudo certbot certonly --standalone -d jira.example.com # Ubuntu
$ sudo ./certbot-auto certonly --standalone -d jira.example.com # CentOS/RHEL

Set it all up


I did this on an Ubuntu 16.04 machine. I used the OpenJDK 8 for my Java install, so my $JAVA_HOME is /usr/lib/jvm/java-8-openjdk-amd64/jre

$ sudo su - # Become root (much easier)
    
# cd $JAVA_HOME

Create a PKCS12 that contains both your full chain and the private key

# openssl pkcs12 -export -out /tmp/jira.example.com_fullchain_and_key.p12 -in /etc/letsencrypt/live/jira.example.com/fullchain.pem -inkey /etc/letsencrypt/live/jira.example.com/privkey.pem -name jira

Convert that PKCS12 to a JKS

# keytool -importkeystore -deststorepass 1234 -destkeypass 1234 -destkeystore jira.jks -srckeystore /tmp/jira.example.com_fullchain_and_key.p12 -srcstoretype PKCS12 -srcstorepass 1234 -alias jira

If the system gives you a warning about PKCS12, it may tell you to run the following. Go ahead.

# keytool -importkeystore -srckeystore jira.jks -destkeystore jira.jks -deststoretype pkcs12

Create a backup of <JIRA_INSTALL>/conf/server.xml before editing it. Edit the HTTPS connector so that it has the parameters that point to the KeyStore:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxHttpHeaderSize="8192" SSLEnabled="true"
    maxThreads="150" minSpareThreads="25"
    enableLookups="false" disableUploadTimeout="true"
    acceptCount="100" scheme="https" secure="true"
    sslEnabledProtocols="TLSv1.2,TLSv1.3"
    clientAuth="false" useBodyEncodingForURI="true"
    keyAlias="jira" keystoreFile="/usr/lib/jvm/java-8-openjdk-amd64/jre/jira.jks"
    keystorePass="1234" keystoreType="JKS"/>

Edit the HTTP connector so that it redirects to the HTTPS connector:

<Connector acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true" enableLookups="false" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" port="8080" protocol="HTTP/1.1" redirectPort="8443" useBodyEncodingForURI="true"/>

Save the changes to server.xml

If redirection to HTTPS will be used (this is recommended), edit the <JIRA_INSTALL>/WEB-INF/web.xml file and add the following section at the end of the file, before the closing </web-app>. In this example, all URLs except attachments are redirected from HTTP to HTTPS.

<security-constraint>
    <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>
	    <url-pattern>/issues/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
	    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>

Restart JIRA after you have saved your changes.

See https://confluence.atlassian.com/adminjiraserver/running-jira-applications-over-ssl-or-https-938847764.html#RunningJIRAapplicationsoverSSLorHTTPS-commandline for Troubleshooting tips

Make sure to setup a cronjob that runs every 89 days to update the Letsencrypt certificate.

$ sudo certbot renew

You can try it out by doing:

$ sudo certbot renew --dry-run

Letsencrypt will lock you out if you try to renew too many times in a short period of time, so use the --dry-run option when testing to see if it works!

@stefanjm

This comment has been minimized.

Copy link

commented Oct 15, 2018

Thanks! This works as of today. Couple of remarks though:

  • When converting PKCS12 to JKS, for simplicity's sake use the same password for both "deststorepass" and "destkeypass".
    Running the "Warning" recommended command, It will ask for a "srckeystore" passphrase, that's the password you gave for "deststorepass" and "destkeypass".
  • "srcstorepass" is the "Export" password you chose when creating PKCS12.
  • In server.xml you'll have to copy-paste the whole <Connector port="8443".... </> , there isn't one to edit.
    Also since Apache Tomcat version 8.5.32 you will also have to add the relaxedPathChars="[]|" relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" inside the HTTPS <connector port="8443"..... </> tags or else it will throw an error when visiting the Jira site, asking you to do so.
@beerendlauwers

This comment has been minimized.

Copy link

commented Dec 24, 2018

Quick heads-up: on Ubuntu 18.04, I encountered the following problem:

$ sudo apt-get install certbot
Reading package lists... Done
Building dependency tree
Reading state information... Done
Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:

The following packages have unmet dependencies:
 certbot : Depends: python3-certbot (= 0.28.0-1+ubuntu18.04.1+certbot+4) but it is not going to be installed
E: Unable to correct problems, you have held broken packages.

That turned out to be this issue, which is solved by

sudo add-apt-repository universe
sudo apt-get update
@ZachisGit

This comment has been minimized.

Copy link

commented Jan 4, 2019

Confluence / Jira version of your excellent guide: https://github.com/ZachisGit/Confluence-Jira-HTTPS-Self-Hosted/blob/master/README.md

I adapted your jira guide and added a confluence part to it. I also updated the default paths for e.g. <JIRA_HOME>, how to start/stop jira/confl and other things I had to google while using your guide.

@captainhook

This comment has been minimized.

Copy link

commented Jan 20, 2019

@beerendlauwers Would you happen to have a guide/tips on doing this for the latest version with Tomcat 8.5.32 on Ubuntu 18.04? I think I broke my config by trying to change to port 80 😿

@mpopof

This comment has been minimized.

Copy link

commented Jan 31, 2019

Hey guys, have any of you experienced any problems with cert renewal I'm weird errors and can't get the renewal to work. Ubuntu 16.04. Everything else is working just not the cert renewal.
error like this
Type: unauthorized
Detail: Invalid response from

@mTrax-

This comment has been minimized.

Copy link

commented Mar 22, 2019

Renewal is not working for me neither, I have to recreate everything.

@NiallBegley

This comment has been minimized.

Copy link

commented Apr 11, 2019

Just a heads up - I believe the official guidance from cerbot is that you should run a cron job to attempt certificate renewals every day, not every 89 days as you specify. You'll only hit the renewal limit if you use the --force-renewal flag. Certbot will automatically detect if your current certificate is within the valid period and will skip renewal:

Attempting to renew certificate
Saving debug log to /var/log/letsencrypt/letsencrypt.log

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Processing /etc/letsencrypt/renewal/jira.example.com.conf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cert not yet due for renewal

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The following certs are not due for renewal yet:
  /etc/letsencrypt/live/jira.example.com/fullchain.pem expires on 2019-07-08 (skipped)
No renewals were attempted.
No hooks were run.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Here's the documentation from cerbot:

If you’re sure that this command executes successfully without human intervention, you can add the command to crontab (since certificates are only renewed when they’re determined to be near expiry, the command can run on a regular basis, like every week or every day). In that case, you are likely to want to use the -q or --quiet quiet flag to silence all output except errors.

If you are manually renewing all of your certificates, the --force-renewal flag may be helpful; it causes the expiration time of the certificate(s) to be ignored when considering renewal, and attempts to renew each and every installed certificate regardless of its age. (This form is not appropriate to run daily because each certificate will be renewed every day, which will quickly run into the certificate authority rate limit.)

@iWoodsman

This comment has been minimized.

Copy link

commented Jul 6, 2019

Just to be clear, the suggestion that one remember to renew the Letsencrypt cert should probably also be accompanied by text to the effect, "renewing the cert is not enough; you need to repeat this same procedure every 90 days to update the keystore file. Or script it."

@pabshazon

This comment has been minimized.

Copy link

commented Sep 30, 2019

Hi, I think we are missing a step on the renewal process, to make the new certificate renewed by certbot into the keystoreFile referenced in the Jira server.xml.

I am thinking in creating a .sh script and add it to a post renew hook - https://certbot.eff.org/docs/using.html?highlight=hook#pre-and-post-validation-hooks.

Will let you know how it goes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.