Lesson in Brief: Downloading Keycloak And Configuring The Configuration File

So far in this Keycloak 17 series, we have been preparing our server by installing Ubuntu, MySQL, and downloading our SSL certificate. Now it's time to download the star of the show, Keycloak 17, and do our final bit of preparation before we can get it started. Without further ado...

Installing Dependencies And Other Set Up

Our dependency section is similar to before and, as with previous versions, Keycloak requires Java, so the first thing we'll do is get that installed. We're assuming that your Ubuntu machine is up and running and you've logged in either directly or via SSH. At the command prompt, type the following and hit enter:

sudo apt install openjdk-11-jdk

You may need to enter your password, confirm yes at the prompt to install and wait for this to complete. Next, you should have Wget installed already, used for downloading content and files from web servers, which you can check with the first command and install with the second if you don't have it:

wget -V

sudo apt install wget

Now, install the zip package so we can unzip our Keycloak software after we download it. Enter the command:

sudo apt install zip

And, as the last part of our dependencies and utilities, check if you have a text editor called Nano as we'll need it to update some text files, and if not then install it:

nano -V

sudo apt install nano

Downloading And Preparing Keycloak

As before, we'll create a directory for Keycloak to live in:

sudo mkdir -p /opt/keycloak

Now to downloading Keycloak - we're using the version current at the time of writing, so you will need to check the URL used below and adjust accordingly. Head over to the Keycloak Downloads page and check the URL for the zip file for "Keycloak - Distribution powered by Quarkus". If you are using a different version, be sure to update the version number in all the commands below where it is used.

Please note that as of 2022-04-04, Keycloak 17.0.1 appears to have issues that result in a blank page after logging into the admin console when using port 443. These issues are currently being investigated and the recommendation is to use 17.0.0 for the time being.

Using the Wget package, download Keycloak and save it to the directory we just created:

sudo wget https://github.com/keycloak/keycloak/releases/download/17.0.0/keycloak-17.0.0.zip -P /opt/keycloak

That shouldn't take long, and now we can unzip the file we downloaded:

sudo unzip /opt/keycloak/keycloak-17.0.0.zip -d /opt/keycloak

After hitting enter on the above command, the screen will look a bit like The Matrix for a while with lots of scrolling commands executing. Give it some time to complete.

To keep things clean along the way, let's delete the zip file as we're done with that now:

sudo rm /opt/keycloak/keycloak-17.0.0.zip

For security reasons, we shouldn't run Keycloak with the root user, so we'll create a new user and group. Enter the first command below, hit enter and then enter the second one:

sudo groupadd -r keycloak

sudo useradd -r -g keycloak -d /opt/keycloak -s /sbin/nologin keycloak

Next, navigate to the opt directory, change the ownership of the keycloak directory to the user and group we created earlier and give the bin directory executable permissions:

cd /opt

sudo chown -R keycloak: keycloak

sudo chmod o+x /opt/keycloak/keycloak-17.0.0/bin/

Updating The Keycloak Configuration File

If you've been following along and wondering why things seem so much easier than with Keycloak 16 and below, the answer is the Keycloak 17 configuration file. This super simple gem of a file is the replacement for all the XML editing we had to do in the previous series. No need to ramble on any further, let's get in there and get it updated:

sudo nano /opt/keycloak/keycloak-17.0.0/conf/keycloak.conf

When that opens, you'll see a simple text file with all lines commented out with the # symbol at the beginning. We're going to uncomment certain lines and update some with the info from our work so far. Replace the placeholder text (in bold) below with your values:

# Basic settings for running in production. Change accordingly before deploying the server.

# Database

# The database vendor.
db=mysql

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=MYSQL_DATABASE_PASSWORD

# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
#db-url=jdbc:postgresql://localhost/keycloak

# Observability

# If the server should expose metrics and healthcheck endpoints.
#metrics-enabled=true

# HTTP

# The file path to a server certificate or certificate chain in PEM format.
https-certificate-file=/etc/letsencrypt/live/keycloak.mydomain.com/fullchain.pem

# The file path to a private key in PEM format.
https-certificate-key-file=/etc/letsencrypt/live/keycloak.mydomain.com/privkey.pem

# The proxy address forwarding mode if the server is behind a reverse proxy.
#proxy=reencrypt

# Do not attach route to cookies and rely on the session affinity capabilities from reverse proxy
#spi-sticky-session-encoder-infinispan-should-attach-route=false

# Hostname for the Keycloak server.
hostname=keycloak.mydomain.com:8443

Note the port number on the hostname at the bottom. We'll come back to that soon. We're done with this, so hit Ctrl-O and then Enter to save and Ctrl-X to exit.

Summary

Nice, we've got Keycloak downloaded and the configuration file all prepped and ready. In our next and final article, we'll get Keycloak up and running, make sure it loads when the machine boots, and look at next steps for FileMaker. Almost there! Click here to proceed to the final article in the series.