Chapter 4. Security and Authentication of HawtIO

For some runtimes that support Hawtio RBAC (role-based access control), HawtIO provides a custom Jolokia restrictor implementation that provides an additional layer of protection over JMX operations based on the ACL (access control list) policy.

To activate the HawtIO RBAC restrictor, configure the Jolokia parameter restrictorClass via System property to use io.hawt.web.RBACRestrictor as follows:

jolokia.restrictorClass = io.hawt.system.RBACRestrictor

HawtIO is just a web application in terms of Quarkus, so the various mechanisms Quarkus provides are used to authenticate HawtIO in the same way it authenticates a Web application.

Here we show how you can use the properties-based authentication with HawtIO for demonstrating purposes.

Example:

See Quarkus example for a working example of the properties-based authentication.

See Keycloak Integration - Quarkus chapter which uses Quarkus OIDC support at server side and Keycloak specific JavaScript library to handle OpenID Connect authentication in the browser..

To use Spring Security with HawtIO:

Example:

See Spring Boot-security example for a working example.

If you try to connect to a remote Spring Boot application with Spring Security enabled, make sure the Spring Security configuration allows access from the HawtIO console. Most likely, the default CSRF protection prohibits remote access to the Jolokia endpoint and thus causes authentication failures at the HawtIO console.

See Keycloak Integration - Spring Boot chapter which uses Spring Security OAuth2 support at server side and Keycloak specific JavaScript library to handle OpenID Connect authentication in the browser.

HawtIO can integrate with Jetty JAAS mechanisms. However not all Jetty JAAS modules work out of the box.

Jetty JAAS modules work with Jetty security infrastructure and the important thing is that it requires your web application (WAR) to use <login-config> configuration.

HawtIO provides customized org.eclipse.jetty.security.jaas.spi.PropertyFileLoginModule which is available in io.hawt.jetty.security.jaas.PropertyFileLoginModule class that lifts the restriction of having a <login-config> configuration. Additionally HawtIO provides ready to use *.mod file which can be copied directly to $JETTY_BASE/modules. This file describes Jetty module with references to required HawtIO Jetty library:

[description]
HawtIO JAAS Login Module Configuration for Jetty

[tags]
security
hawtio

[depends]
jaas

[files]
maven://io.hawt/hawtio-jetty-security/<version>|lib/hawtio-jetty-security-<version>.jar

[lib]
lib/hawtio-jetty-security-<version>.jar

After adding`` $JETTY_BASE/modules/hawtio-jetty-security.mod` file we can add this module (and jaas module) using:

$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-module=jaas,hawtio-jetty-security
INFO  : jaas            initialized in ${jetty.base}/start.d/jaas.ini
INFO  : hawtio-jetty-security initialized in ${jetty.base}/start.d/hawtio-jetty-security.ini
INFO  : copy ~/.m2/repository/io/hawt/hawtio-jetty-security/4.6.1/hawtio-jetty-security-<version>.jar to ${jetty.base}/lib/hawtio-jetty-security-<version>.jar
INFO  : Base directory was modified

To use authentication with Jetty, you first have to set up some users with credentials and roles. To do that navigate to $JETTY_BASE/etc/ folder and create etc/login.properties file containing something like this:

etc/login.properties
scott=tiger,user
admin=CRYPT:adpexzg3FUZAk,admin,user

You have added two users: . The first one named scott with the password tiger, with the role user assigned to it. . The second user admin with password admin which is obfuscated (see password Obfuscation in Jetty documentation for details). This one has the admin and user role assigned.

Now create the second file in the same $JETTY_BASE/etc/ directory named login.conf. This is the JAAS login configuration file.

hawtio {
  io.hawt.jetty.security.jaas.PropertyFileLoginModule required
  debug="true"
  file="${jetty.base}/etc/login.properties";
};

Change the HawtIO configuration:

When Jetty jvm module is installed, we can specify HawtIO properties in $JETTY_BASE/start.d/jvm.ini:

--exec
-Dhawtio.authenticationEnabled=true
-Dhawtio.realm=hawtio
-Dhawtio.roles=admin
-Dhawtio.userPrincipalClasses=org.eclipse.jetty.security.UserPrincipal
-Dhawtio.rolePrincipalClasses=org.eclipse.jetty.security.jaas.JAASRole

Without jvm module the above options should be specified as system properties when running java -jar $JETTY_HOME/start.jar.

You have now enabled authentication for HawtIO. Only users with role admin are allowed to log in.

HawtIO configuration properties can be passed to Tomcat using CATALINA_OPTS environment variable. This variable should contain system properties recognized by HawtIO.

By default, HawtIO authentication is enabled. You can disable authentication in Tomcat by adding this to bin/setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -Dhawtio.authenticationEnabled=false"

HawtIO will auto-detect that it is running in Tomcat. It will add dynamic JAAS login module that will be used to authenticate users declared in Tomcat’s conf/tomcat-users.xml file. All configuration options related to this file are supported by HawtIO. Additionally, when the file is modified, Hawtio will reload the user database.

The simplest content of conf/tomcat-users.xml may be:

<?xml version="1.0"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml" version="1.0">
  <user username="scott" password="tiger" roles="tomcat"/>
</tomcat-users>

The above definition includes single scott user with tiger password assigned with tomcat role.

However, HawtIO also supports encoded/hashed password (see more details in Tomcat documentation on CredentialHandler). Tomcat itself may be configured like this:

<?xml version="1.0" encoding="UTF-8"?>
<Server port="8005" shutdown="SHUTDOWN">
  ...
  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">
    ...
    <Engine name="Catalina" defaultHost="localhost">
      ...
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase">
          <CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler" algorithm="SHA-384" />
        </Realm>
      </Realm>
      ...
    </Engine>
  </Service>
</Server>

This tells Tomcat that the passwords are hashed using SHA-384 message digest algorithm. With such configuration, conf/tomcat-users.xml may look like this:

<?xml version="1.0"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml" version="1.0">
  <user username="hawtio" password="<salt>$<iteration count>$<digest>" roles="admin,manager,..."/>
</tomcat-users>

HawtIO supports all password formats specified in the MessageDigestCredentialHandler documentation.

If you only want users of a special role to be able to login Hawtio, you can set the role name in the CATALINA_OPTS environment variable as shown:

CATALINA_OPTS="$CATALINA_OPTS -Dhawtio.roles=Administrator,Operator"

Now the user must be in the Administrator or Operator role to be able to login, which we can set up in the conf/tomcat-users.xml file:

<role rolename="manager"/>
<user username="scott" password="tiger" roles="Administrator"/>

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:

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:

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

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

{
  "realm": "hawtio-demo",
  "clientId": "hawtio-client",
  "url": "http://localhost:18080/",
  "jaas": false,
  "pkceMethod": "S256",
  "logoutUri": "/hawtio/auth/logout"
}

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

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

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