Keycloak Integration

This chapter presents the legacy method of integration between Hawtio and Keycloak. This method relies on the availability of Keycloak libraries and Keycloak-specific configuration files, as well as client side keycloak.js library.

Starting with Keycloak 25.0.0, Keycloak specific login modules are no longer available. For generic OpenID Connect integration (which also supports Keycloak server), please refer to OpenID Connect Integration chapter.

You can secure your Hawtio console with Keycloak. To integration Hawtio with Keycloak, you need to:

  1. Prepare Keycloak server

  2. Deploy Hawtio to your favourite runtime (Quarkus, Spring Boot, WildFly, Karaf, Jetty, Tomcat, etc.) and configure it to use Keycloak for authentication

Prepare Keycloak server

Install and run Keycloak server. The easiest way is to use a Docker image:

docker run -d --name keycloak \
  -p 18080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak start-dev

Here we use port number 18080 for the Keycloak server to avoid potential conflicts with the ports other applications might use.

You can log in to the Keycloak admin console http://localhost:18080/admin/ with user admin / password admin. Import hawtio-demo-realm.json into Keycloak. To do so, click Create Realm button and then import hawtio-demo-realm.json. It will create hawtio-demo realm.

The hawtio-demo realm has the hawtio-client application installed as a public client, and defines a couple of realm roles such as admin and viewer. The names of these roles are the same as the default Hawtio roles, which are allowed to log in to Hawtio admin console and to JMX.

There are also 3 users:

admin

User with password admin and role admin, who is allowed to login into Hawtio.

viewer

User with password viewer and role viewer, who is allowed to login into Hawtio.

jdoe

User with password password and no role assigned, who is not allowed to login into Hawtio.

Currently, the difference in roles does not affect Hawtio access rights on Quarkus and Spring Boot, as Hawtio RBAC functionality is not yet implemented on those runtimes.

Configuration

Hawtio’s configuration for Keycloak integration consists of two parts: integration with Keycloak in the runtime (server side), and integration with Keycloak in the Hawtio console (client side).

The following settings need to be made for each part:

Server side

The runtime-specific configuration for the Keycloak adapter

Client side

The Hawtio Keycloak configuration keycloak-hawtio.json

Starting with Keycloak 25.0.0, Keycloak specific login modules are no longer available. Keycloak can be used with Hawtio using OpenID Connect Integration. We can also use Quarkus or SpringBoot specific support for OAuth2 / OpenID Connect which doesn’t rely on Keycloak libraries.

Quarkus

Firstly, apply the required configuration for attaching Hawtio to a Quarkus application.

What you need to integrate your Quarkus application with Keycloak is Quarkus OIDC extension. Add the following dependency to pom.xml:

pom.xml
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc</artifactId>
</dependency>

Server side

Then add the following lines to application.properties (which configures the server-side OIDC extension):

application.properties
quarkus.oidc.auth-server-url = http://localhost:18080/realms/hawtio-demo
quarkus.oidc.client-id = hawtio-client
quarkus.oidc.credentials.secret = secret
quarkus.oidc.application-type = web-app
quarkus.oidc.token-state-manager.split-tokens = true
quarkus.http.auth.permission.authenticated.paths = "/*"
quarkus.http.auth.permission.authenticated.policy = authenticated
quarkus.oidc.token-state-manager.split-tokens = true is important, as otherwise you might encounter a large size session cookie token issue and fail to integrate with Keycloak.

Client side

Finally create keycloak-hawtio.json under src/main/resources in the Quarkus application project (which serves as the client-side Hawtio JS configuration):

keycloak-hawtio.json
{
  "realm": "hawtio-demo",
  "clientId": "hawtio-client",
  "url": "http://localhost:18080/",
  "jaas": false,
  "pkceMethod": "S256",
  "logoutUri": "/hawtio/auth/logout"
}
Set pkceMethod to S256 depending on Proof Key for Code Exchange Code Challenge Method advanced settings configuration. If PKCE is not enabled, do not set this option.

Build and run the project and it will be integrated with Keycloak.

Example

See quarkus-keycloak example for a working example.

Spring Boot

Firstly, apply the required configuration for attaching Hawtio to a Spring Boot application.

What you need to integrate your Spring Boot application with Keycloak is to add the following Spring Boot dependencies to pom.xml:

pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Server side

Then add the following lines in application.properties (which configures the server-side Keycloak adapter):

application.properties
hawtio.authenticationEnabled = true
hawtio.keycloakEnabled = true
hawtio.keycloakClientConfig = classpath:keycloak-hawtio.json

spring.security.oauth2.client.provider.keycloak.issuer-uri = http://localhost:18080/realms/hawtio-demo
spring.security.oauth2.client.registration.keycloak.client-id = hawtio-client
spring.security.oauth2.client.registration.keycloak.authorization-grant-type = authorization_code
spring.security.oauth2.client.registration.keycloak.scope = openid

Client side

Finally create keycloak-hawtio.json under src/main/resources in the Spring Boot project (which serves as the client-side Hawtio JS configuration):

keycloak-hawtio.json
{
  "realm": "hawtio-demo",
  "clientId": "hawtio-client",
  "url": "http://localhost:18080/",
  "jaas": false,
  "logoutUri": "/actuator/hawtio/auth/logout"
}

Build and run the project and it will be integrated with Keycloak.

Example

See springboot-keycloak example for a working example.