Security

Hawtio enables authentication out of the box depending on the runtimes/containers it runs with. To use Hawtio with your application, either setting up authentication for the runtime or disabling Hawtio authentication is necessary.

Configuration properties

The following table lists the Security-related configuration properties for the Hawtio core system.

Table 1. Security-related configuration properties
Name	Default	Description
`hawtio.authenticationContainerDiscoveryClasses`	`io.hawt.web.tomcat.TomcatAuthenticationContainerDiscovery`	List of used `AuthenticationContainerDiscovery` implementations separated by comma. By default there is just `TomcatAuthenticationContainerDiscovery`, which is used to authenticate users on Tomcat from `tomcat-users.xml` file. Feel free to remove it if you want to authenticate users on Tomcat from configured JAAS login module or feel free to add more classes of your own.
`hawtio.authenticationContainerTomcatDigestAlgorithm`	`NONE`	When using the Tomcat `tomcat-users.xml` file, passwords can be hashed instead of plain text. Use this to specify the digest algorithm; valid values are `NONE`, `MD5`, `SHA`, `SHA-256`, `SHA-384`, `SHA-512`.
`hawtio.authenticationEnabled`	`true`	Whether or not security is enabled.
`hawtio.authenticationThrottled`	`true`	Whether to throttle authentication to protect Hawtio from brute force attacks.
`hawtio.keycloakClientConfig`	`classpath:keycloak.json`	Keycloak configuration file used for frontend. It is mandatory if Keycloak integration is enabled.
`hawtio.keycloakEnabled`	`false`	Whether to enable or disable Keycloak integration.
`hawtio.noCredentials401`	`false`	Whether to return HTTP status 401 when authentication is enabled, but no credentials has been provided. Returning 401 will cause the browser popup window to prompt for credentials. By default this option is `false`, returning HTTP status 403 instead.
`hawtio.realm`	`hawtio`	The security realm used to login.
`hawtio.rolePrincipalClasses`		Fully qualified principal class name(s). Multiple classes can be separated by a comma.
`hawtio.roles`	`admin,manager,viewer`	The user roles required to be able to login to the console. Multiple roles to allow can be separated by a comma. Set to `*` or an empty value to disable role checking when Hawtio authenticates a user.
`hawtio.tomcatUserFileLocation`	`conf/tomcat-users.xml`	Specify an alternative location for the `tomcat-users.xml` file, e.g. `/production/userlocation/`.

Quarkus

Hawtio can be secured with the authentication mechanisms Quarkus provides, as well as Keycloak.

if you want to disable Hawtio authentication for Quarkus, add the following configuration to application.properties:

application.properties

quarkus.hawtio.authenticationEnabled = false

Quarkus authentication mechanisms

Hawtio is just a Web application in terms of Quarkus, so the various mechanisms Quarkus provides can be 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.

The properties-based authentication is not recommended to use in production. This mechanism is for development and testing purposes only.

To use the properties-based authentication with Hawtio, add the following dependency to pom.xml:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-elytron-security-properties-file</artifactId>
</dependency>

You can then define users to application.properties to enable the authentication. For example, defining a user hawtio with password s3cr3t! and role admin would look like the following:

application.properties

quarkus.security.users.embedded.enabled = true
quarkus.security.users.embedded.plain-text = true
quarkus.security.users.embedded.users.hawtio = s3cr3t!
quarkus.security.users.embedded.roles.hawtio = admin

Example

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

Quarkus with Keycloak

See Keycloak Integration - Quarkus.

Spring Boot

In addition to the standard JAAS authentication, Hawtio on Spring Boot can be secured through Spring Security or Keycloak.

if you want to disable Hawtio authentication for Spring Boot, add the following configuration to application.properties:

application.properties

hawtio.authenticationEnabled = false

Spring Security

To use Spring Security with Hawtio, add org.springframework.boot:spring-boot-starter-security to the dependencies in pom.xml:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Spring Security configuration in src/main/resources/application.properties should look something like the following:

spring.security.user.name = hawtio
spring.security.user.password = s3cr3t!
spring.security.user.roles = admin,viewer

A security config class has to be defined to set up how to secure the application with Spring Security:

@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated()
            .and()
            .formLogin()
            .and()
            .httpBasic()
            .and()
            .csrf().csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse());
        return http.build();
    }
}

Example

See springboot-security example for a working example.

Connecting to a remote application with Spring Security

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.

The easiest solution is to disable CSRF protection for the Jolokia endpoint at the remote application as follows.

Be aware that it will expose your application at risk of CSRF attacks.

import org.springframework.boot.actuate.autoconfigure.jolokia.JolokiaEndpoint;
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;

@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        ...
        // Disable CSRF protection for the Jolokia endpoint
        http.csrf().ignoringRequestMatchers(EndpointRequest.to(JolokiaEndpoint.class));
        return http.build();
    }

}

To secure the Jolokia endpoint even without Spring Security’s CSRF protection, you need to provide a jolokia-access.xml file under src/main/resources/ like the following (snippet) so that only trusted nodes can access it:

<restrict>
  ...
  <cors>
    <allow-origin>http*://localhost:*</allow-origin>
    <allow-origin>http*://127.0.0.1:*</allow-origin>
    <allow-origin>http*://*.example.com</allow-origin>
    <allow-origin>http*://*.example.com:*</allow-origin>

    <strict-checking />
  </cors>
</restrict>

Spring Boot with Keycloak

See Keycloak Integration - Spring Boot.

Web containers

Hawtio authentication is enabled by default. If you want to disable Hawtio authentication, set the following system property:

hawtio.authenticationEnabled = false

Jetty

To use authentication with Jetty, you first have to set up some users with roles. To do that navigate to the etc/ folder of your Jetty installation and create the following file etc/login.properties and enter 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. He has the role user assigned to it. The second user admin with password admin which is obfuscated (see Jetty realms for possible encryption methods). This one has the admin and user role assigned.

Now create the second file in the same etc/ directory called login.conf. This is the login configuration file.

etc/login.conf

hawtio {
  org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required
  debug="true"
  file="${jetty.base}/etc/login.properties";
};

Currently the login module org.eclipse.jetty.jaas.spi.PropertyFileLoginModule doesn’t work with Hawtio. The instructions are kept as-is for illustrative purposes. But to really make it work, use different login modules or implement your own PropertyFileLoginModule.

Next, enable the JAAS module in Jetty. This is done by the following command:

$ java -jar $JETTY_HOME/start.jar --add-module=jaas

At last, you have to change the Hawtio configuration:

Table 2. Configuration properties for Jetty authentication
Property	Value
`hawtio.authenticationEnabled`	`true`
`hawtio.realm`	`hawtio`
`hawtio.roles`	`admin`
`hawtio.rolePrincipalClasses`	`org.eclipse.jetty.jaas.JAASRole`

You have now enabled authentication for Hawtio. Only users with role admin are allowed for login.

Apache Tomcat

Hawtio configuration properties can be passed to Tomcat using CATALINA_OPTS environment variable.

By default, Hawtio authentication is enabled. Let’s set up realm to * to make it work with the Tomcat built-in realm:

export CATALINA_OPTS=-Dhawtio.realm=*

Hawtio will auto-detect that it is running in Tomcat, and use its user data file (conf/tomcat-users.xml) for security. For example, to set up a new user named scott with password tiger, then edit the file conf/tomcat-users.xml to include:

<user username="scott" password="tiger" roles="tomcat"/>

Then you can login to Hawtio with the username scott and password tiger.

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:

export CATALINA_OPTS="-Dhawtio.realm=* -Dhawtio.role=manager"

Now the user must be in the manager 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="tomcat,manager"/>

Using different login modules

If you want to use your own login modules instead of conf/tomcat-users.xml file, you can do it by removing TomcatAuthenticationContainerDiscovery from system properties and pointing to login.conf file with your login modules configuration, something like:

export CATALINA_OPTS="-Dhawtio.authenticationContainerDiscoveryClasses= -Dhawtio.realm=hawtio -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.conf"

Then you can configure JAAS in file TOMCAT_HOME/conf/login.conf (see Jetty for an example of the file).

Keycloak Integration

Hawtio can be integrated with Keycloak for SSO authentication. See Keycloak Integration.