Getting started with Keycloak powered by Quarkus

Throughout this article, we will delve into the best practices for installing and running Keycloak powered by Quarkus, exploring topics such as Keycloak authentication, Keycloak authorization, and secure microservice architecture. By the end, you’ll unlock the potential of Keycloak powered by Quarkus,

Keycloak overview

Keycloak is an Identity Provider that enables you to secure your Web applications by providing Single Sign-On (SSO) capabilities and leveraging industry standards such as OpenID Connect (OIDC), Single Sign-On (SSO) and Identity and Access Management (IAM).

So far, the runtime of Keycloak distribution was WildFly application server. To deliver a faster and leaner server, Keycloak now builds on the top of Quarkus. The new distribution format is ideal for a Microservice environment where fast start up applications with a small footprint is a must.

In the next section we will learn how to install, start and configure Keycloak (powered by Quarkus) using development and production settings.

Installing Keycloak powered by Quarkus

Requirements: To run a Keycloak server you need Java on your machine. Please note that Java 11 was deprecated in Keycloak 21 therefore we recommend running Keycloak with Java 17.

The latest version of Keycloak at April 2024 is version 24.0.3 and it is available at: https://www.keycloak.org/downloads

Firstly, download an unzip it in a folder of your like. Before we get started, it is important to know that you can run Keycloak in two operating modes:

• Development mode: You can activate this operating mode with the start-dev command. This mode relaxes some requirements in terms of security/hostname resolution therefore it’s ideal when developing or testing.
• Production mode: You can activate this mode when you use the build and start command. This mode has stricter requirements therefore we recommend using it for real world scenarios.

Then, you should know that Keycloak uses a different set of files to start and configure the server. Here is the tree view of the project:

.
├── bin
│   ├── client
│   ├── kcadm.bat
│   ├── kcadm.sh
│   ├── kc.bat
│   ├── kcreg.bat
│   ├── kcreg.sh
│   └── kc.sh
├── conf
│   ├── cache-ispn.xml
│   ├── keycloak.conf
│   └── README.md
├── data
│   └── h2
├── lib
│   ├── app
│   ├── lib
│   ├── quarkus
│   └── quarkus-run.jar
├── LICENSE.txt
├── providers
│   └── README.md
├── README.md
├── themes
│   └── README.md
└── version.txt

Core files:

• kc.sh / kc.bat the script you can use to start Keycloak.
• kcadm.sh / kcadm.bat the script to launch commands from the Command Line
• keycloak.conf: this file contains the server configuration options using the key=value format

Starting Keycloak in development mode

You can start Keycloak in development mode as follows:

./kc.sh start-dev 

Check that the server started successfully:

When running in development mode, Keycloak uses by default an H2 Database to store its configuration and is available on port 8080.

For your first access, access the Admin Console and create an Admin User. By default, the Admin Console is available at: http://localhost:8080

TIP: If you cannot access the Admin Console, you can also create an user by exporting the following environment variables:

export KEYCLOAK_ADMIN=<username>
export KEYCLOAK_ADMIN_PASSWORD=<password>

On the other hand, if you want to start Keycloak on a different port, use the –http-port option. Example:

./kc.sh start-dev --http-port=8180

Finally, to check other available options, you can use:

./kc.sh start-dev --help

Start Keycloak in Production mode

To start the Identity Server in production mode, you have to meet some requirements, with regards to hostname resolution and security. Also, in production mode, you can start the server in two steps:

• build phase: this is where Quarkus optimizations take place, the configuration files are pre-parsed and changes are persisted in the image. You need to rebuild your configuration when you move from development mode to production.
• run phase: this is where you start Keycloak and you can optionally set values to any of the configuration options

Let’s see how to accomplish these steps, using a production ready database like PostgreSQL.

Firstly, we will start PostgreSQL DB. The default keycloak Database name is “keycloak” therefore we will start PostgreSQL as Docker image with these settings:

docker run -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=keycloak -e POSTGRES_USER=postgres -d -p 5432:5432 postgres

Next, we need to provide a keystore for the server. To create it in JKS format with keytool:

keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 365 -keystore server.keystore -dname "cn=Server Administrator,o=Acme,c=GB" -keypass secret -storepass secret

By default the keystore is searched in the conf folder of the distribution. Therefore, if you copy it in that location, you won’t need to provide extra parameters at start up.

cp server.keystore /home/keycloak/keycloak-21.1.1/conf

We are now ready for the build phase, where we can set as default Database PostgreSQL:

./kc.sh build --db postgres

Finally, the last step is to start Keycloak:

./kc.sh start --db-url-host localhost --db-username postgres --db-password postgres --hostname=fedora --https-key-store-password=secret

java.lang.RuntimeException: Strict hostname resolution configured but no hostname was set

Here is Keycloak up and running in Production mode:

Securing applications with Keycloak

We have covered some key aspects of the latest Keycloak release. In terms of securing applications you should remove the default /auth context from Keycloak URL. This is because, by default, Keycloak with Quarkus uses the Root Web context.

To keep publishing the HTTP Security Context under the /auth server URL you can use the http-relative-path option:

./kc.sh start-dev --http-relative-path /auth

Next, let’s see how to adapt your configuration from this tutorial Secure WildFly applications with OpenID Connect

We will start Keycloak in development mode. Remove any keystores (if any) from the conf folder , and start the server on port 8180 to avoid clashing with WildFly:

./kc.sh start-dev --http-port=8180

Then, run the kcadm.sh script to create the Realm wildfly-realm and the Client configuration customer-manager-client:

./kcadm.sh config credentials --server http://localhost:8180 --realm master --user admin --password admin

./kcadm.sh create realms -s realm=wildfly-realm -s enabled=true -o

./kcadm.sh create users -r wildfly-realm -s username=customer-admin -s enabled=true

./kcadm.sh set-password -r wildfly-realm --username customer-admin --new-password admin

./kcadm.sh create clients -r wildfly-realm -s clientId=customer-manager-client -s publicClient="true"  -s "redirectUris=[\"http://localhost:8080/*\"]" -s enabled=true

./kcadm.sh create roles -r wildfly-realm -s name=customer-manager

./kcadm.sh add-roles --uusername customer-admin --rolename customer-manager -r wildfly-realm

As you can see, the only relevant change is the first line, where use have removed the /auth context from the –server parameter.

In terms of application code you don’t need any change but you must update the oidc.json with the correct auth-server-url_

{
  "realm": "wildfly-realm",
  "auth-server-url": "http://localhost:8180/",
  "ssl-required": "external",
  "resource": "customer-manager-client",
  "public-client": true,
  "confidential-port": 0
}

Then, rebuild your WildFly application and login with the user credentials (“customer-admin” / “admin”). You will be able to access the Secured Servlet:

Conclusion and Source code

In conclusion, mastering the integration of Keycloak powered by Quarkus is a pivotal step towards achieving secure user authentication and authorization in your applications. By implementing Keycloak’s robust features, such as OpenID Connect (OIDC), Single Sign-On (SSO), and role-based access control (RBAC), you can fortify your application’s security while providing a seamless user experience.

The source code for the Keycloak configuration is available here: https://github.com/fmarchioni/mastertheboss/tree/master/bootable-jar/elytron-oidc-client-keycloak17