user-icon Andreas Falk
14. February 2022
timer-icon 7 min

Keycloak with Quarkus: Better together

By changing the underpinning from the Wildfly application server to Quarkus as the new standard, Keycloak with Quarkus now finally becomes cloud-native. This blog post is the first part of a new series of articles on Keycloak and shows the new installation and configuration options of the Quarkus-based distribution.
Keycloak and Quarkus

Starting with released version 17.0.0, the default Keycloak distribution is now based on Quarkus. As a result, the WildFly based distribution is marked as deprecated. To ensure a smooth migration the legacy distribution will continue to be supported until June 2022.

The main advantages of Keycloak with Quarkus are:

  • Immutability of containers
  • Faster startup, and smaller footprint
  • Significantly simplified configuration

For those who don’t know Keycloak, in short, it provides the following features:

  • It acts as an identity provider supporting standards like OAuth, OpenID Connect, and SAML 2.0.
  • Keycloak provides local user storage and adapters to integrate other user bases (for instance LDAP).
  • It can integrate 3rd party identity providers.
  • It provides an administration UI and a REST API for configuration.

In this article, I will describe the new configuration options and ways to install Keycloak. This covers both, productive use and development purposes.

How to install Keycloak with Quarkus

To install Keycloak as Quarkus distribution you have a choice of different options:

In the further course of this article, I will guide you through the bare metal installation option.

Installation on bare metal

Before running Keycloak on your local machine make sure you have JDK 11 or newer installed.
The next step is to grab the Keycloak with Quarkus distribution (as zip or tar.gz file) from the keycloak download server.
After extracting the downloaded archive file, as a result, you should find a directory named keycloak-x.x.x (depending on the actual version). In the bin subdirectory, you can find the required scripts to start Keycloak on your machine.

Running and configuring Keycloak with Quarkus

First, to start and configure Keycloak please download and extract Keycloak as described in the install section for bare metal. Secondly, please open a terminal and change the directory to the location where you extracted Keycloak into.
To start Keycloak you have two options:
  1. Run Keycloak in development mode (just for quick local prototyping or general local development)
  2. Run Keycloak in production mode (as the name suggests: For secure productive purposes)
With switching to quarkus, the configuration mechanism has changed as well. As a result, to configure Keycloak, you now have the following possibilities:
  1. Via command-line option as part of kc.sh or kc.bat command (e.g. –db-url-host=myhost)
  2. By setting an environment variable (i.e. set KC_DB_URL_HOST=myhost)
  3. By specifying the configuration option in the configuration file conf/keycloak.conf (e.g. db-url-host=myhost)

Run Keycloak in Development Mode

The development mode is intended for quickly setting up Keycloak on your developer machine. This takes up just some minutes. In development mode, Keycloak is using unsecured HTTP mode and stores data into an H2 database (not production-ready).
Finally, start Keycloak in development mode using the following command:
After the start has been completed (which now takes only a very short time) please navigate to http://localhost:8080.
First, you will be forced to configure the administrative user account. For development purposes, you may just use simple credentials like admin as username and password. In the end, confirm this by clicking on the create button.
keycloak first start
After completing this, you will see a link to open the administration console. Please click this link to see the predefined master realm of Keycloak.
keycloak master realm
That’s it. Now you can directly start using Keycloak by adding your own realm and clients for OAuth / OpenID Connect or SAML 2.0.
Especially when restarting Keycloak the second time you will notice the much faster start of Keycloak with Quarkus. With the legacy stack based on the Wildfly application server, it took minutes to boot up.
Please note: As the name suggests, this mode is only intended for development purposes.
If you want to set up Keycloak for productive purposes then follow the next section.

Run Keycloak in Production Mode

To run Keycloak in the productive mode you use the following command (using Mac or Linux):
or this one (using Windows):
Unfortunately, when starting Keycloak with the command above you will get the following error:
ERROR: Failed to start server in (production) mode
ERROR: Strict hostname resolution configured but no hostname was set
This error is caused by missing additional required configuration parameters for the production mode.
Running Keycloak in production mode requires you to configure at least the following:
  • Enabling TLS: As Keycloak exchanges sensitive data (like access tokens), all communication needs to use a secure communication channel. Hence, you must enable HTTP over TLS, or HTTPS.
  • Setting the hostname for Keycloak: When running Keycloak in productive environments, you have to set the public-facing internet hostname.
  • Configure a production-grade database: The database used by Keycloak is crucial for the overall performance, availability, reliability, and integrity. Therefore, it is needed to use a production-ready database like PostgreSQL or MySQL instead of H2.

Please look into the guide for production configuration for further details.

Enabling TLS

Keycloak by nature uses sensitive data like access tokens. As a result, Keycloak should transmit any data over a secured transport layer only. Therefore using TLS and HTTPS is mandatory for production mode.

 Set up a local CA
Before enabling TLS we need to set up a local certificate authority (trusted by local java or web browser installations). In a second step, we will issue a corresponding TLS certificate for Keycloak.
To achieve both steps we will make use of a convenient tool called mkcert. You can grab and install this from https://github.com/FiloSottile/mkcert.
The first step is to configure a local certificate authority (CA) on your machine.
This is done via the following command:
This should have an output similar to the following:
The local CA is already installed in the system trust store! 👍
The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (requires browser restart)! 🦊
The local CA is now installed in Java’s trust store! ☕️
Generate the certificate
In the previous step, we have created a CA with a corresponding root certificate. The root certificate is automatically installed into Java and web browsers. After that, we can generate a private/public key pair and a certificate (including the public key). This will be required to enable TLS in Keycloak later.
To generate the certificate and the private key:
  1. Change into the Keycloak directory.
  2. Create a new subdirectory called tls.
  3. Change into this subdirectory, and then use the following command:
This should be followed by this output:
Created a new certificate valid for the following names 📜
– “localhost”
– “keycloak.local”
The certificate is at “./localhost 1.pem” and the key at “./localhost 1-key.pem” ✅
It will expire on 13 May 2024 🗓
The generated certificate will be valid for localhost and keycloak.local domains. To use the keycloak.local domain on your machine, you have to locally configure this. For instance, on Linux and Mac, you can achieve this by adding it to the /etc/hosts file.

When looking into the tls subdirectory you will find the following files:

  • localhost 1.pem (the certificate)
  • localhost 1-key.pem (the private key)

To make it easier later just rename the files to localhost.pem and localhost-key.pem.

To enable TLS for Keycloak you have to add the following options to the start command:
  • –https-certificate-file=/opt/keycloak-17.0.0/tls/localhost.pem (replace with your path to the certificate file)
  • –https-certificate-key-file=/opt/keycloak-17.0.0/tls/localhost-key.pem (replace with your path to the key file)
  • –https-protocols=TLSv1.3,TLSv1.2 (the currently recommended TLS protocol versions)
Let’s continue with the configuration of the hostname.

Setting the hostname

Keycloak distinguishes the hostname for the following application parts:
  • Frontend Endpoints: Frontend endpoints are used to externally access Keycloak. When no hostname is set, the base URL used for the frontend is taken from the incoming request.
  • Backend Endpoints: Backend endpoints are used for direct communication between Keycloak and applications like for instance the Token endpoint. Backend endpoints are also taking the base URL from the request by default.
  • Administrative Endpoints: To further reduce the attack surface, the administration endpoints for Keycloak and the Admin Console should not be publicly accessible. Therefore, you can secure them by using a reverse proxy. By specifying –hostname-admin=<adminHostname> you can separate the administrative part from the other parts.
For setting the hostname add the following options to the start command:
  • –hostname=keycloak.local:8443 (this sets the hostname with the required port for HTTPS)
  • –hostname-strict-backchannel=true (this forces all requests to use the specified hostname and not the URL from the request)
In the following section, you will configure PostgreSQL as a production-grade database for Keycloak.

Configure a production-grade database

As part of this blog post, I will use a PostgreSQL database for Keycloak. You may use one of the following supported databases:
  • MariaDB
  • Microsoft SQL Server
  • MySQL
  • Oracle
  • PostgreSQL
To configure Keycloak to use PostgreSQL you issue the following command:
Here I assume that a PostgreSQL database named keycloak has already been created with a corresponding role named keycloak and a password with the same value.
So you have to add the following database connection options to the start command:
  • –db-url-host=127.0.0.1 (the database hostname or IP address)
  • –db-url-database=keycloak (the name of the database to use)
  • –db-username=keycloak (the user authorized to connect to the database)
  • –db-password=keycloak (the corresponding password for the user)
If you want to know more about database configuration please consult the corresponding guide.
With that, we finally have all required configuration options complete and we are now able to start Keycloak in production.
So let’s dive into the next section for this.

Startup the productive Keycloak server

In this final section, we are able to start Keycloak in production mode. Let’s see what the corresponding command looks like.

When navigating to https://keycloak.local:8443 the first step is again to set up the administrative user.
keycloak first start
Moreover, you will see that the local Keycloak instance is using the HTTPS protocol with a valid TLS certificate.
keycloak with TLS
If you try to configure the administrative user via the web console on a remote machine you will encounter an error. This is prohibited because of potential security risks. Therefore, creating the administrative user via the web admin console is only allowed when running on localhost.
As a consequence, you have to set the following environment variables first before executing the start command:

Final words

In conclusion, I showed you how to make the switch to the new Keycloak with Quarkus distribution. I discussed the advantages you get by using the new Quarkus distribution. You learned about the new configuration possibilities and the differences between the development and production modes.
In the next parts of this blog series, I will look at further aspects of Keycloak like:
  • Describing more configuration options like using a reverse proxy or setting up cluster mode
  • A walk through the administration interface of Keycloak
  • Creating an OAuth / OpenID Connect client.
  • And much more
Image Sources: https://pixabay.com/de/illustrations/id-fahrerlaubnis-4157974/

Comment article

Comments

  1. Indiphile

    Your article is perfect. Thank you.

    11. May 2022 |
  2. Iulian Peca

    Hello,

    Thanks for the nice article. If I have a cluster of 3 nodes (let’s say node1.local.com,node2.local.com,node3.local.com,) with a loadbalancer in front for internal access (lb-internal.local.com, like communication with application) and another loadbalancer (lb-external.local.com) for external access, what is the hostname that I should use?

    11. April 2022 |
  3. Jon Cruz

    Thanks for sharing these steps/instructions.

    I was looking at upgrading my Keycloak v14 instances when I noticed the switch from WildFly to Quarkus.

    This article gives me more than a head start on doing so, and I’m looking forward to you next posts.

    23. February 2022 |

Recent posts

logo_white_stroke
Privacy Policy

Here you will find an overview of all cookies used. You can give your consent to whole categories or view more information to select only certain cookies.

Essential cookies enable basic functions and are necessary for the proper functioning of the website.

Statistics Cookies collect information anonymously. This information helps us to understand how our visitors use our website.

Content from video and social media platforms is blocked by default. If cookies are accepted by external media, access to this content no longer requires manual consent.