dborin/jira_letsencrypt.md

## jira_letsencrypt.md

      
        

                
      Raw
    
  

        
        
          
            
          
          
            
              jira_letsencrypt.md
            
          
        
      
      
    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!