Keycloak Integration

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

Prepare Keycloak server
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

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"
}

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 dependency to pom.xml (replace 4.x.y with the latest Hawtio release version):

pom.xml

<dependency>
  <groupId>io.hawt</groupId>
  <artifactId>hawtio-springboot-keycloak</artifactId>
  <version>4.x.y</version>
</dependency>

Server side

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

application.properties

keycloak.realm = hawtio-demo
keycloak.resource = hawtio-client
keycloak.auth-server-url = http://localhost:18080/
keycloak.ssl-required = external
keycloak.public-client = true
keycloak.principal-attribute = preferred_username

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
}

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

Example

See springboot-keycloak example for a working example.

Jetty

Keycloak adapters are deprecated. The instructions in this section are not verified with Hawtio v3. It will be updated.

Assume $JETTY_HOME is the root directory of your Jetty installation and you deployed Hawtio WAR to Jetty as described in Get Started.

Install Keycloak Jetty adapter into your Jetty server as described on the Keycloak documentation.

Download and copy keycloak-hawtio.json and keycloak-bearer.json into Jetty. File keycloak-bearer.json is currently used for adapters on server (JAAS Login module) side. File keycloak-hawtio.json is used on client (Hawtio JS application) side.

cp examples/keycloak-integration/keycloak-hawtio.json $JETTY_HOME/etc/
cp examples/keycloak-integration/keycloak-bearer.json $JETTY_HOME/etc/

Create file $JETTY_HOME/etc/login.conf with the content like this:

hawtio {
    org.keycloak.adapters.jaas.BearerTokenLoginModule required
        keycloak-config-file="${hawtio.keycloakServerConfig}";
};

Export JETTY_HOME in your terminal. For example:

export JETTY_HOME=/mydir/jetty-distribution-9.x.x

Export JAVA_OPTIONS and add all necessary system properties similarly like this:

export JAVA_OPTIONS="-Dhawtio.authenticationEnabled=true \
                     -Dhawtio.realm=hawtio \
                     -Dhawtio.keycloakEnabled=true \
                     -Dhawtio.roles=admin,manager,viewer \
                     -Dhawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal \
                     -Dhawtio.keycloakClientConfig=$JETTY_HOME/etc/keycloak-hawtio.json \
                     -Dhawtio.keycloakServerConfig=$JETTY_HOME/etc/keycloak-bearer.json \
                     -Djava.security.auth.login.config=$JETTY_HOME/etc/login.conf"

Run Jetty and go to http://localhost:8080/hawtio. Users are again admin and viewer with access and jdoe without access.

Tomcat

Keycloak adapters are deprecated. The instructions in this section are not verified with Hawtio v3. It will be updated.

Instructions are quite similar to Jetty. You would need to setup JAAS realm and set the system properties. Just use Tomcat adapter instead of the Jetty one. Also you may need to add this system property (really empty value):

-Dhawtio.authenticationContainerDiscoveryClasses=

This is needed, so that Tomcat will use configured JAAS realm with BearerTokenLoginModule instead of tomcat-users.xml file, which Hawtio uses on Tomcat by default.