Skip to content

Instantly share code, notes, and snippets.

@dborin
Last active February 3, 2024 10:09
Show Gist options
  • Star 29 You must be signed in to star a gist
  • Fork 11 You must be signed in to fork a gist
  • Save dborin/dd501b28967d3784fa646534dbea6ffa to your computer and use it in GitHub Desktop.
Save dborin/dd501b28967d3784fa646534dbea6ffa to your computer and use it in GitHub Desktop.
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!

@beerendlauwers
Copy link

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
Copy link

ZachisGit 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
Copy link

@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
Copy link

mpopof 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-
Copy link

mTrax- commented Mar 22, 2019

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

@NiallBegley
Copy link

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
Copy link

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
Copy link

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.

@leonfizz
Copy link

leonfizz commented Apr 1, 2020

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.

Any news on this?

@davidrhoderick
Copy link

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.

Yes, this would be nice to know; renewal doesn't work...

@programkom
Copy link

also, if you're using http redirect to http, dont forget to add relaxedPathChars="[]|" relaxedQueryChars="[]|{}^\`"<>" to redirect connector...

@virshu
Copy link

virshu commented Sep 20, 2021

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.

any links how to make the new certificate into keystore? I see that fullchain.pem is referencing new .pem file; but the website still shows old certificate

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment