Keycloak 17 & FileMaker: Installation & Configuration Tutorial
Duncan Baker, Sounds Essential Blog
Part 1: Ubuntu & MySQL
Introduction
As we have before, we need to acknowledge the excellent work from Wim Decorte and Steven Blackwell who have and continue to push the subject of security in the FileMaker platform. Our forays into Keycloak can entirely be attributed to their work in this area and we are indebted to them. Please read their series of white papers here to learn about various external authentication options for FileMaker.
We will be referring back to previous articles for certain steps and procedures, so if this is new to you, do read the introductory article of our previous series to get familar with what’s what.
Keycloak 17: What’s Changed?
Keycloak 16 and previous versions were built upon an underlying technology called WildFly. For a couple of years now, the Keycloak team have been working on transitioning away from WildFly to something called Quarkus, using the project name Keycloak.X. Well, that transition is complete and the first release of the new underlying technology is now fully supported and available as Keycloak 17.
This new and improved version promises to be “be lighter, faster, easier, more scalable, more cloud native, and a bunch of other things” according to Keycloak themselves. And our experience in testing Keycloak 17 confirms this. Deployment is far easier and Keycloak boots up far quicker – seconds rather than a minute or two.
While the underpinnings are completely new, if you’re already familar with Keycloak, you’ll be pleased to hear that much of the admin interface remains the same so there’s not a huge re-learning curve ahead of you there. In addition, if you’re using a version before 15.1.1, it fixes a known security vulnerability. So, it’s time to jump on the Quarkus Keycloak train – all aboard, we’re about to get going…
Installing Ubuntu
There are various ways of deploying Keycloak, but as we have before, we’ll be using a straight up Linux server. We’ll be using Ubuntu Server 20.04.3 LTS which you can download from here (Option 2). Next, figure out your hardware to install on:
- Hyper-V on Windows 10 (probably Windows 11 too but we’ve not upgraded yet!)
- VMware
- Parallels
- Amazon Web Services or other cloud provider
- Old Mac Mini you have kicking around
- Something else…
You can follow our Part 1: Installing Ubuntu article if you need help with this. Once you have that installed and updated, with a command prompt at the ready, move on to the next section.
Installing MySQL
We’ll be using MySQL as the database for Keycloak and the steps to install are as we have done previously, but we’re including them here for completeness and clarity. First up, let’s make sure we’re at the root directory:
cd
Now, install the MySQL server package, confirming yes at the prompt:
sudo apt install mysql-server
And then we’ll run the security script to set things up:
sudo mysql_secure_installation
You’ll be asked a series of questions:
- If you wish to use the Validate Password component, which enforces password complexity. Given we’re trying to improve security, this is not a bad option to elect yes for.
- After that, enter your password for the MySQL root user – our placeholder for this is MYSQL_ADMIN_PASSWORD
- Next you’ll be asked to remove the anonymous user – select yes.
- And then disallow root login remotely – again yes.
- Then remove the test database.
- Finally, reload the privileges table.
Next, we’ll create our database.
Creating The Database
Creating the database is pretty straightforward… Be sure to switch out our placeholder MYSQL_DATABASE_PASSWORD with your own (note this is not the same password as the MYSQL_ADMIN_PASSWORD and if you set up password validation rules above, ensure it complies with those):
sudo mysql
CREATE DATABASE keycloak CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'keycloak'@'localhost' IDENTIFIED BY 'MYSQL_DATABASE_PASSWORD';
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'localhost';
FLUSH PRIVILEGES;
exit;
You should be back at the command prompt. And that’s it, we’re done with MySQL. Wait, what? Really? Is that all? Yup… Remember how we said above that deployment was much easier? Ladies and gentlemen, I present to you, Keycloak 17… No more messing around with XML.
For good measure, let’s reboot.
sudo shutdown -r now
Tools
For those of you that have traversed our previous Keycloak tutorials, are disappointed at how simple this has been so far and were expecting a scrolling, scrolling article, sorry. But also not sorry… To fill some page space though, a quick note on some tools we used during this testing and tutorial series.
- Hyper-V
- We’ve talked about this virtualization technology before
- It’s included in Windows and is free
- You can create Checkpoints, so if you mess something up or just want to experiment, you can revert back to the clean install of Ubuntu without having to start from scratch
- Run multiple instances of different operating systems or software on one machine
- Export images of operating systems/installations
- Again, it’s free – there’s nothing to stop you from trying out Keycloak!
- iTerm2
- https://iterm2.com
- This is a Terminal replacement on Mac
- It’s free
- You can save Snippets, paste history, make notes and more
- We’ve only just started using this and the jury is still out but it seems to be a step up on the default Terminal program
- There are others such as Termius that we’ll be keeping an eye on too
Summary
So, we have our Linux server up and running with a MySQL database ready and waiting for Keycloak to hook into. Next up, that security beast that is SSL certificates. Onward to the next article, part two!
Keycloak 17 & FileMaker: Installation & Configuration Tutorial Part 2: Let’s Encrypt SSL Certificate
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.
Keycloak 17 & FileMaker: Installation & Configuration Tutorial Part 3: Preparing Keycloak 17
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.
Keycloak 17 & FileMaker: Installation & Configuration Tutorial Part 4: Starting Keycloak 17 & Next Steps
Lesson in Brief: Starting Keycloak 17 Including On Boot And Next Steps
We’re approaching the finish line with our Keycloak 17 series, with just a couple more things to take care of. In this final article, we’ll be getting our Keycloak server up and running, along with getting it to start when the machine reboots, and looking at some port considerations and next steps for integrating with FileMaker. Let’s get this finished up!
Starting Keycloak
At the end of the last article, we adjusted the Keycloak configuration file. Everytime that configuration gets changed, you need to execute the command below to rebuild the server configuration – don’t forget to do this or you’ll either get an error message or your updates just won’t show. So, we’re going to navigate to the correct folder, build the server, set some environment variables with our initial Keycloak admin username and password (be sure to update the placeholders with your own credentials), then start the server, make sure we can get to it, then kill it… We’ll explain why…
cd /opt/keycloak/keycloak-17.0.0
sudo bin/kc.sh build
export KEYCLOAK_ADMIN=username
export KEYCLOAK_ADMIN_PASSWORD=password
sudo -E bin/kc.sh start
Note that the -E attribute is only necessary on the initial boot, in order to load up the environment variables which set the initial admin credentials. Should you have a need to do a manual start again at some point, omit this.
Give it about a minute to get up and running (it needs to create the database schema). Once you see the lines similar to the below, it should be ready (note timestamps have been omitted):
INFO [org.keycloak.services] (main) KC-SERVICES0050: Initializing master realm INFO [org.keycloak.services] (main) KC-SERVICES0009: Added user 'username' to realm 'master' INFO [io.quarkus] (main) Keycloak 17.0.0 on JVM (powered by Quarkus 2.7.0.Final) started in 70.268s. Listening on: https://0.0.0.0:8443 INFO [io.quarkus] (main) Profile prod activated. INFO [io.quarkus] (main) Installed features: [agroal, cdi...
Then in a browser and go to (update to your domain) https://keycloak.mydomain.com:8443. You should see the Welcome to Keycloak page with the Administration Console link available.
Sweet! It’ll be tempting to click the admin link and start exploring, but hold your horses there… We ran into some issues when we stopped Keycloak very soon after starting it up, so go grab a coffee or something and leave things as they are for about 5 minutes.
Ok, left it for a while? Great, let’s stop Keycloak by hitting Ctrl-Z. Now we’ll set up a systemd unit file for it to run when the machine boots.
Configuring Keycloak To Start Up On Boot
Let’s just jump in and make a new text file in the correct directory:
sudo nano /etc/systemd/system/keycloak.service
Now, copy and paste the text below into that file – you shouldn’t need to make any changes if you’ve been following along:
# /etc/systemd/system/keycloak.service [Unit] Description=Keycloak Server After=syslog.target network.target mysql.service Before=httpd.service [Service] User=keycloak Group=keycloak
SuccessExitStatus=0 143 ExecStart=!/opt/keycloak/keycloak-17.0.0/bin/kc.sh start [Install] WantedBy=multi-user.target
Again hit Ctrl-O and Enter to save and then Ctrl-X to exit the text editor. Now we’ll reload the daemon, enable the service and reboot!
sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo shutdown -r now
Once the machine has rebooted, give it about 10 seconds and then check to see if Keycloak is running:
sudo systemctl status keycloak
If that shows “active (running)” then you’re good and you should be able to access Keycloak using the link above. Hit Ctrl-Z to exit that.
DISCLAIMER: It should be pointed out that the systemd unit file, as it is currently set up, is using elevated privileges to start Keycloak, which is not ideal. However, issues encountered during testing required this and we could find no alternative. We hope at some point these issues can be resolved and we will update this article accordingly when that time comes. While we hope to keep these tutorials as simple as possible for greater adoption, another approach would be to use a reverse proxy to work around this issue.
Port Configuration
Keycloak’s default SSL port is 8443. During testing, we found that we needed to add this port number to the hostname in the configuration file. If we didn’t, the Welcome To Keycloak page would load (on port 8443) but when clicking the Administration Console link, the address switched to plain https without a port number (essentially port 443). We’re not sure if this is a bug or intended but it was one of the things that threw us during our exploration of Keycloak 17.
As we’ve pointed out in previous articles, currently FileMaker Server only allows for a custom IdP to run on port 443 – we can only hope that at some point this will change. So if you want to run Keycloak for FileMaker, we need to run it on 443. Open the configuration file again, remove the port number from the hostname entry and add the https-port as below:
sudo nano /opt/keycloak/keycloak-17.0.0/conf/keycloak.conf
# Hostname for the Keycloak server. hostname=keycloak.mydomain.com
# Use port 443
https-port=443
Hit Ctrl-O and Enter to save and then Ctrl-X to exit the text editor. Don’t forget, you adjusted the Keycloak configuration file so you need to do a build:
cd /opt/keycloak/keycloak-17.0.0
sudo bin/kc.sh build
As we’ve changed the port we’re using from the default Keycloak SSL port to standard SSL, we need to update the firewall rules – we’ll delete the 8443 rule and allow 443:
sudo ufw delete allow 8443/tcp
sudo ufw allow 443/tcp
You can always check the status of the firewall by running the command below:
sudo ufw status
Now let’s reboot one final time:
sudo shutdown -r now
Next Steps
So, now you have your Keycloak server up and running, what’s next? Well, setting up FileMaker to work with it would be a great option!
Configuring Keycloak For FileMaker Server:
- Learn how to set up an instance of FileMaker Server in Keycloak, within the Admin console: Setting Up A Keycloak Server For Authenticating To FileMaker: Part 5: Configuring Keycloak
If you’re below FileMaker Server 19.4:
- Consider upgrading!
- Use our guide here to configure FileMaker Server: Setting Up A Keycloak Server For Authenticating To FileMaker: Part 6: Configuring FileMaker
If you’re at or above FileMaker Server 19.4:
- Woo hoo, your life just became way easier!
- Use our guide here to configure FileMaker Server: Setting Up A Keycloak Server For Authenticating To FileMaker: Part 9: Custom IdP Options In FileMaker 19.4
And then:
- Set up two-factor authentication: Setting Up A Keycloak Server For Authenticating To FileMaker: Part 7: Configuring Two Factor Authentication
- Set up password-less authentication (very cool!): Setting Up A Keycloak Server For Authenticating To FileMaker: Part 8: Secure Password-Less Authentication
- If you’re using, say, Google for authentication but would like to utilize groups, head over to an article by Jason Wood of Define Database for FileMaker group-based authentication with Google and Keycloak.
Finally, there’s plenty more to explore with Keycloak, depending on your individual set up and needs. Head over to their:
- Documentation section for an overview
- All configuration options for that super sweet configuration file
- The Keycloak blog for all their latest news
- And there’s a pretty active Keycloak forum for questions or browsing what others are having trouble with
Summary
So, that’s Keycloak 17 in a nutshell, or less of a nutshell than it used to be. We’re excited by the move to Quarkus, and with 17.0.0 being the initial release on the new underlying technology, we can only expect that more improvements, with community feedback, will be forthcoming. If the speed and frequency of previous Keycloak releases are anything to go by, we’re in for some treats ahead! But, fundamentally, this is all about securing your FileMaker solutions with the offerings of modern security – two-factor or multi-factor authentication, YubiKeys and so forth. If you have the slightest interest, please give Keycloak a shot, you won’t be disappointed. And if you’d like some help, don’t hesitate to contact us. Good luck. Stay secure.
