Lesson in Brief: Obtaining A Let's Encrypt SSL Certificate For Keycloak 17

Our previous Keycloak article on SSL certificates has been, by far, the most popular article in the series. Undoubtedly, it's not just FileMaker developers visiting that page, but it's encouraging that the security article within the security series has picked up that much traction. We must encrypt the traffic between our servers, be that Keycloak or FileMaker, and again to that end we'll be utilizing Let's Encrypt certificates for Keycloak 17.

Introduction

We will not be covering all the explanations about domains/sub-domains and firewall ports in this article as that was explained previously. If you're unsure about these aspects, please visit the introductory paragraphs of our previous article to get up to speed. We will be using similar steps/commands as before and again we are including them here for the series completeness and clarity.

Installing Certbot

We'll be installing a small utility called Certbot that will handle retrieving and updating our SSL certificate. There are a number of commands to execute, so enter them one by one confirming yes as needed, being sure to check for errors:

sudo snap install core

sudo snap refresh core

sudo snap install --classic certbot

sudo ln -s /snap/bin/certbot /usr/bin/certbot

sudo shutdown -r now

Wait for the server to reboot and then log back in again.

Configuring The Firewall

While it could be argued that the server is behind a router or AWS Security Groups, it's not a bad idea to enable the firewall on our Linux machine and open only the ports that we need. So, let's ensure the ssh port is open, we need to open firewall port 80 for Certbot to communicate on, and while we're at it we'll open the default SSL port that Keycloak uses (as previously mentioned, you may need to open external firewall ports and set up port forwarding):

sudo ufw allow ssh

sudo ufw allow 80/tcp

sudo ufw allow 8443/tcp

sudo ufw enable

Obtaining A SSL Certificate

With the firewall in place, we can request our certificate by running the command below, ensuring you update the domain to the one you wish to use. Note the use of the parameter --dry-run which allows for testing without consequence. Use this first time round and then remove it to request the certificate for real.

sudo certbot certonly --standalone --preferred-challenges http -d keycloak.mydomain.com --dry-run

You'll be prompted for your email address and to accept the terms of service. If all your firewall settings are right then you should get a message to say the dry run was successful. If it wasn't successful then you'll need to check those firewall settings both on the Linux machine and your external firewall. Assuming your dry run was successful, run the above command again but remove the --dry-run parameter at the end - you'll be asked an additional question about sharing your email address. Read the message carefully and answer as you wish.

Congratulations! Your certificate and chain have been saved and you should see your expiry date. WIthin that success message, you should see a file path to where the certificates were saved. It should be something along the lines of:

/etc/letsencrypt/live/keycloak.mydomain.com

Take note of this file path, we're going to need it later.

Let's close that firewall port now that we have our certificate downloaded:

sudo ufw deny 80/tcp

Renewing The SSL Certificate Automatically

As we did in Part 3 of the previous series, we want to make sure that our Let's Encrypt certificates renew automatically so our authentication server doesn't suddenly stop working on us. We'll blaze through the steps here with similar explanations as before.

When we installed Certbot, it created a timer for us. We can confirm that with:

sudo systemctl list-units --type timer

You should see one called snap.certbot.renew.timer. If you don't then try enabling it and run the above command again:

sudo systemctl enable snap.certbot.renew.timer

It's also possible to check on the status of the timer using:

sudo systemctl status snap.certbot.renew.timer

When Certbot checks for a new certificate, it again does so over port 80. As we'd rather not leave port 80 open all the time, we'll use Let's Encrypt's pre and post hook functions to open and close the port for us.

cd /etc/letsencrypt/renewal-hooks/pre

Make a new file called pre-hook.sh

sudo nano pre-hook.sh

And then paste the below into that file - be sure that it looks like the below and those commands are not all on one line after pasting:

#!/bin/bash
# Open port 80
ufw allow 80/tcp

Hit Ctrl-O and Enter to save and Ctrl-X to exit the editor. Now we need to make that file executable:

sudo chmod +x pre-hook.sh

And now let's do the same procedure for the post hook and closing the port:

cd /etc/letsencrypt/renewal-hooks/post

Make a new file called post-hook.sh

sudo nano post-hook.sh

Paste the below into that file - again make sure there are multiple lines after pasting:

#!/bin/bash
# Close port 80
ufw deny 80/tcp

Hit Ctrl-O and Enter to save and Ctrl-X to exit the editor. Again we need to make that file executable:

sudo chmod +x post-hook.sh

Ok, so Certbot is ready to update our certificate. Previously we had a deploy script. but no need to have that on this occasion. You can test the renewal procedure by executing this command:

sudo certbot renew --dry-run

That's it, we're done. Whoa! That's it? Again? Well, for the SSL certificate, yes. Deployment is far easier with Keycloak 17...

Summary

So, in preparing our server for Keycloak 17, we've installed Ubuntu, set up our database and have our SSL certificate downloaded and ready to go. In our next article, we download Keycloak 17 and do a spot of configuration.