Access Manager: Using free Let's Encrypt SSL certificates

Introduction

It is recommended that you use an SSL certificate that has been signed by a Certificate Authority as the default self-signed certificate will give trust errors in a web browser.

Until recently this means that you had to purchase such a certificate.

This article shows you how you can use the free SSL certificate service provided by Let's Encrypt.

Reconfiguring Access Manager static content folder

By default Access Manager will serve static files from the /static folder. This will not work with Let's Encrypt as it requires a folder on the web server called /.well-known.

**WARNING** If you are already serving content from the /static folder, you will no longer be able to access that content via /static after this change. Your existing data will not be deleted but it will only be available from ./well-known after this.

To do this, in a shell we need to create a new config file, let's call it static-root.cfg.

vi /etc/nervepoint/forker.d/static-root.cfg

In that file, paste this line (press i to enter insert mode, then paste):
jvmarg -Dnervepoint.staticRoot=/.well-known

Now save the file with ESC, then :x and restart the service with:

/etc/init.d/nervepoint restart

After this restart, any file that is placed into /etc/nervepoint/static-content will appear on your web server under the /.well-known folder.

Now the certbot client that will be used will attempt to write its files out onto the local filesystem into a folder called .wellknown, so we need to create a symlink to ensure the files get placed into the static-content filter with:

ln -s /etc/nervepoint/static-content /etc/nervepoint/.well-known

Creating the initial certificate

Now download certbot-auto from the let's encrypt site:
cd /root
wget https://dl.eff.org/certbot-auto
chmod a+x ./certbot-auto

Note: At this point, your Access Manager server needs to be externally accessible on port 443, as the let's encrypt servers will make a connection to your server to validate it.

Run the following command to generate the first certificate, replacing <hostname> with your own external hostname that your users will connect to:

./certbot-auto certonly --webroot -w /etc/nervepoint/ -d <hostname>

The above command should give you output like the following:

root@nam13testing:~# ./certbot-auto certonly --webroot -w /etc/nervepoint/ -d oldportal.hypersocket.com
Creating virtual environment...
Installing Python packages...
Installation succeeded.
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator webroot, Installer None
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for oldportal.hypersocket.com
Using the webroot path /etc/nervepoint for all unmatched domains.
Waiting for verification...
Cleaning up challenges

IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/etc/letsencrypt/live/oldportal.hypersocket.com/fullchain.pem
Your key file has been saved at:
/etc/letsencrypt/live/oldportal.hypersocket.com/privkey.pem
Your cert will expire on 2018-03-22. To obtain a new or tweaked
version of this certificate in the future, simply run certbot-auto
again. To non-interactively renew *all* of your certificates, run
"certbot-auto renew"
- If you like Certbot, please consider supporting our work by:

Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
Donating to EFF: https://eff.org/donate-le

At this stage, you will have one key and 3 certificates in /etc/letsencrypt/live/yourhostname.

We now need to take those files and create a PKCS12 file, then import that into the Java Keystore.

Create a new file:

vi /root/importCertToAccessManager.sh

Paste in the following contents and save the file (many thanks to Joseph Benson for this script):

#!/bin/bash

# Copyright 2017 ROCKHARBOR Church, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This script grabs the new/renewed Let's Encrypt key and full certificate chain, packs them in a
# pkcs12 file, and imports the contents into the Nervepoint JKS store with the alias Jetty, after deleting
# the existing key. It then restarts the Nervepoint service to activate the new certificate.
# You should call it as the --deploy-hook parameter of Certbot, which passes in the variable RENEWED_LINEAGE
# as the source of the certificate and key. You can also call it from the command line at initial install with
# the first argument being the path to the privkey.pem and fullchain.pem files.
if [ ! -z "$1" ]
then
RENEWED_LINEAGE=$1
fi
plaintextKeyfile=$RENEWED_LINEAGE/privkey.pem
encryptedKeyfile=$RENEWED_LINEAGE/privkey_enc.pem
fullchainFile=$RENEWED_LINEAGE/fullchain.pem
pkcs12File=$RENEWED_LINEAGE/certificate.p12
nervepointConfigRoot=/etc/nervepoint

# Let's Encrypt outputs a plaintext keyfile but Jetty expects it to be encrypted.
# Encrypts it with 3DES and the default password "changeit"
openssl rsa -des3 -in $plaintextKeyfile -out $encryptedKeyfile -passout "pass:changeit"

# Creates a pkcs12 file with both the encrypted key and the full certificate chain
openssl pkcs12 -export -inkey $encryptedKeyfile -in $fullchainFile -passin "pass:changeit" -name "jetty" -passout "pass:changeit" -out $pkcs12File

# Deletes the old key and certificate from the JKS store and imports from the pkcs12 file
keytool -delete -alias "jetty" -keystore /etc/nervepoint/keystore -storepass "changeit"
keytool -importkeystore -srckeystore $pkcs12File -srcstoretype "pkcs12" -srcstorepass "changeit" -srcalias "jetty" -destkeystore $nervepointConfigRoot/keystore -deststoretype "JKS" -deststorepass "changeit" -destalias "jetty"

# Restarts the Nervepoint service
/etc/init.d/nervepoint restart

Save the file and give it execute permissions with:

chmod 755 /root/importCertToAccessManager.sh

Importing the certificate

We need to run this script manually the first time to import the certificate just created:
/root/importCertToAccessManager.sh /etc/letsencrypt/live/<hostname>/

The script will import the script and restart the Access Manager service.

Your Access Manager server should now be running with a Let's Encrypt certificate. However there is one final step to perform to ensure the certificate remains valid.

Automatically renewing the certificate

As Let's Encrypt certificates only have a 90 day validity, we need to configure an automation to perform the renewal. We will do this with a cron job that runs once per day. If the certificate has less than 30 days left, the certbot script will then automatically update the certificate.

Edit the crontab with:

crontab -e

First, pick a random time of day that is not midnight. This is to spread the load that hits Let's Encrypt's servers. For this example, we will choose 05:15 in the morning.

Add a new line to the file, replacing the minutes and hours part with your own choice:

15 05 * * * /root/certbox-auto renew --deploy-hook /root/importCertToAccessManager.sh

Save the file with CTRL-X then Y and you are done.