To Top

SoundEssential logo span 55px 2
  • News & Information

    News & Information

    News & information for developers & users from the wide world of FileMaker, Claris and beyond

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:

If you're below FileMaker Server 19.4:

If you're at or above FileMaker Server 19.4:

And then:

Finally, there's plenty more to explore with Keycloak, depending on your individual set up and needs. Head over to their:

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.

FileMaker Tutorial Keycloak Keycloak 17