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