Using Let's Encrypt with dotCMS

2/14/17

At the outset, it seemed like I would need to jump through a lot of hoops to get Let's Encrypt to work with dotCMS. As it turns out, the 'certbot' provided by the Electronic Freedom Foundation has a manual mode which is easy enough for even the likes of me to decipher.

Before We Begin . . .

You're going to need shell/terminal access to the server hosting dotCMS. This guide will proceed assuming you will be using a *nix system. The guide will also assume you have taken care of all the DNS necessities to point people (and the Let's Encrypt servers) to your server. You will either need some familiarity with Apache webserver, nGinx or the Java keytool to handle the ssl certificates once they have been generated. Lastly you'll need the ability to add folders and pages to your dotCMS instance.

Get Certbot

First step is to get certbot by the EFF on your system. Certbot exists on most package managers (aptitude/apt-get, yum package manager, etc.) but I had the most luck just manually downloading the bot and setting the correct permissions on it. Do this in some safe directory (like your home directory):

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

Great, now we've got the tool. Let's use it. Fire up the tool in manual certificate-only mode with the following command

./certbot-auto certonly --manual

You will be prompted for you domain or a list of domains. For a single domain use the following format:

fantasticsite.com

www.fatasticsite.com

To cover multiple domains or subdomains use the following format (space separated):

fantasticsite.com www.fantasticsite.com webmail.fantasticsite.com

You will be asked if the IP of your server (or wherever you are running this script from) may be logged. You must select (Y)es to continue as per the EULA.

Finally you will be asked to have your webserver render a certain string of text on a certain page for verification that you control the domain. The page will be of the format;

http://fantasticsite.com/.well-known/acme-challenge/07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4

That final part of the URI is a truncated version of the string you will display on the page. which will be of the following format;

07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4.ZLH2yGi09vC0evR2LhjleO-z0DbEXHRWMDlAl7Sme9s

Having dotCMS Serve the Verification Pages

Log into the backend of dotCMS and open the Site Browser. Create a folder named ".well-known". Create a folder within ".well-known" named "acme-challenge". Next on your local machine create a file with a name matching the final part of the URI (in this example "07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4"). Inside of this file enter the requested verification string (in this example "07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4.ZLH2yGi09vC0evR2LhjleO-z0DbEXHRWMDlAl7Sme9s"). In the Site Browser and inside of /.well-known/acme-challenge/ add the file you just created on your local machine. You should now have a file named "07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4" in /.well-known/acme-challenge/.

Verify that you can access http://fantasticsite.com/.well-known/acme-challenge/07kywwgSLVpBWWdcacW7s5Ug6vbKveQkLLjEVLpjIl4 and that you see the correct validation string.

NOTE: If you have multiple domains, you will need to do a verification page for EACH domain. To issue an SSL certificate for www.fantasticsite.com and fantasticsite.com you will need TWO verification pages. When you've completed the verification page for your first domain just hit "ENTER" in the certbot script and it will specify the verification pages for subsequent domains.

Generate the Certificate

Now the magic can happen. While we were creating the verification URI our certbot script has been patiently waiting for us to continue. It should read "Press ENTER to Continue" just after giving us the instructions to create our verification pages. Hit "ENTER" and cerbot will do its thing. This includes generating a local private key, verifying that you control the domains by looking up the verification pages you just created from the Let's Encrypt server headquarters (wherever those are . . .) and then generating the certificates based off of your private key.

If all goes well you will receive a "Congratulations!" message with some information regarding the certificates' expiration date. Great, you've created the certificates. Now where the heck are they?

Locating and Using the Certificate

I'm going to go through an example using Apache web server but you can adapt this to any webserver.

With Apache and other webservers you're going to need a certificate, a private key to verify this against and a chain certificate to link your certificate up to the root certificate authority. So where did certbot put these? They should live in

/etc/letsencrypt/live/{yourdomain}

All subdomains will be on a single certificate. If you had multiple domains you will have multiple folders inside of /etc/letsencrypt/live/.

In Apache I will need to setup a Virtual Host to listen on port 443. Basically you'll end up with something like below, but you may want to shop around for a config that suits your situation better.

Listen 443 https

<VirtualHost *:443>

    ServerAdmin webmaster@fantasticsite.com

    ServerName fantasticsite.com

    SSLEngine on

    SSLCertificateFile /etc/letsencrypt/live/fantasticsite.com/cert.pem

    SSLCertificateKeyFile /etc/letsencrypt/live/fantasticsite.com/privkey.pem

    SSLCertificateChainFile /etc/letsencrypt/live/fantasticsite.com/chain.pem

    SSLProxyEngine on

    ProxyRequests Off

    ProxyVia On

    <Proxy *>

      Order deny,allow

      Allow from all

    </Proxy>

    ProxyPass /       ajp://localhost:8009/ retry=0

    ProxyPassReverse /     ajp://localhost:8009/ retry=0

</VirtualHost>

This specific configuration depends on having the AJP connector uncommented in dotCMS's server.xml. You could instead proxyPass with http or https instead of ajp. The important parts of this whole process are the following:

Download certbot on your server or your local machine
Run the certbot and get the verification page specifications from Let's Encrypt
Create the verification pages within dotCMS as simple file assets text files with no extension containing the required string of text
Create the certificates once these pages pass verification
Reference these certificates in the SSL portion of whatever web server is handling your dotCMS instance.

Looking Forward

Now you're all set up with SSL! Now what? Well you should probably migrate users from http over to https. You probably want to check for references for insecure content (http sources on an https page) on your pages. Both of these can be handled with some fancy URL rewriting and permanent redirects with whatever web server you are using.