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:
- Install on bare metal
- Running using Docker or Podman
- Deploy on Kubernetes
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:
- Run Keycloak in development mode (just for quick local prototyping or general local development)
- 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:
- Via command-line option as part of kc.sh or kc.bat command (e.g. –db-url-host=myhost)
- By setting an environment variable (i.e. set KC_DB_URL_HOST=myhost)
- 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:
bin/kc.sh start-dev
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.
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.
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):
bin/kc.sh start
or this one (using Windows):
bin\kc.bat start
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:
mkcert -install
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:
- Change into the Keycloak directory.
- Create a new subdirectory called tls.
- Change into this subdirectory, and then use the following command:
mkcert localhost keycloak.local
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)
See the guide on configuring the hostname for details.
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:
bin/kc.sh build --db postgres
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.
bin/kc.sh start --https-certificate-file=/opt/keycloak-17.0.0/tls/localhost.pem --https-certificate-key-file=/opt/keycloak-17.0.0/tls/localhost-key.pem --https-protocols=TLSv1.3,TLSv1.2 --db-url-host=127.0.0.1 --db-url-database=keycloak --db-username=keycloak --db-password=keycloak --hostname=keycloak.local:8443 --hostname-strict-backchannel=true
When navigating to https://keycloak.local:8443 the first step is again to set up the administrative user.
Moreover, you will see that the local Keycloak instance is using the HTTPS protocol with a valid TLS certificate.
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:
export KEYCLOAK_ADMIN=admin export KEYCLOAK_ADMIN_PASSWORD=secret
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
