Securing the Hawtio Administration Console

To secure the Hawtio Administration Console with Keycloak, complete the following steps:

  1. Add these properties to the $FUSE_HOME/etc/system.properties file:

    hawtio.keycloakEnabled=true
    hawtio.realm=keycloak
    hawtio.keycloakClientConfig=${karaf.base}/etc/keycloak-hawtio-client.json
    hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal
  2. Create a client in the Keycloak administration console in your realm. For example, in the Keycloak demo realm, create a client hawtio-client, specify public as the Access Type, and specify a redirect URI pointing to Hawtio: http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, http://localhost:8181).

  3. Create the keycloak-hawtio-client.json file in the $FUSE_HOME/etc directory using the similar content as below. Change the realm, resource, and auth-server-url properties according to your Keycloak environment. The resource property must point to the client created in the previous step. This file is used by the client (Hawtio Javascript application) side.

    {
      "realm" : "demo",
      "resource" : "hawtio-client",
      "auth-server-url" : "http://localhost:8080/auth",
      "ssl-required" : "external",
      "public-client" : true
    }
  4. Create the keycloak-hawtio.json file in the $FUSE_HOME/etc dicrectory using similar content as below. Change the realm and auth-server-url properties according to your Keycloak environment. This file is used by the adapters on the server (JAAS Login module) side.

    {
      "realm" : "demo",
      "resource" : "jaas",
      "bearer-only" : true,
      "auth-server-url" : "http://localhost:8080/auth",
      "ssl-required" : "external",
      "use-resource-role-mappings": false,
      "principal-attribute": "preferred_username"
    }
  5. Start JBoss Fuse 6.3.0.0.Final and install the keycloak feature if you have not already. The commands in Karaf terminal are similar to this example:

    features:addurl mvn:org.keycloak/keycloak-osgi-features/3.0.0.Final/xml/features
    features:install keycloak
  6. Go to http://localhost:8181/hawtio and log in as a user from your Keycloak realm.

    Note that the user needs to have the proper realm role to successfully authenticate to Hawtio. The available roles are configured in the $FUSE_HOME/etc/system.properties file in hawtio.roles.

Securing Hawtio on EAP

To run Hawtio on the Wildfly 10 server, complete the following steps:

  1. Set up Keycloak as in the Securing the Hawtio Administration Console section above. The following assumptions apply: you have a Keycloak realm demo and client hawtio-client, and your Keycloak is running on localhost:8080 while the Wildfly server with deployed Hawtio will be running on localhost:8181.

  2. Copy the hawtio.war archive to the $WILDFLY_HOME/standalone/configuration directory. For more details about deploying Hawtio see the Fuse Hawtio documentation.

  3. Copy the keycloak-hawtio.json and keycloak-hawtio-client.json files with the above content to the $WILDFLY_HOME/standalone/configuration directory.

  4. Install the Keycloak adapter subsystem to your Wildfly server as described in the JBoss adapter documentation

  5. In the $WILDFLY_HOME/standalone/configuration/standalone.xml file configure the system properties as in this example:

    <extensions>
    ...
    </extensions>
    
    <system-properties>
        <property name="hawtio.authenticationEnabled" value="true" />
        <property name="hawtio.realm" value="hawtio" />
        <property name="hawtio.roles" value="admin,viewer" />
        <property name="hawtio.rolePrincipalClasses" value="org.keycloak.adapters.jaas.RolePrincipal" />
        <property name="hawtio.keycloakEnabled" value="true" />
        <property name="hawtio.keycloakClientConfig" value="${jboss.server.config.dir}/keycloak-hawtio-client.json" />
        <property name="hawtio.keycloakServerConfig" value="${jboss.server.config.dir}/keycloak-hawtio.json" />
    </system-properties>
  6. Add the Hawtio realm to the same file in the security-domains section:

    <security-domain name="hawtio" cache-type="default">
        <authentication>
            <login-module code="org.keycloak.adapters.jaas.BearerTokenLoginModule" flag="required">
                <module-option name="keycloak-config-file" value="${hawtio.keycloakServerConfig}"/>
            </login-module>
        </authentication>
    </security-domain>
  7. Add the secure-deployment section hawtio to the adapter subsystem. This ensures that the Hawtio WAR is able to find the JAAS login module classes.

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
        <secure-deployment name="hawtio.war" />
    </subsystem>
  8. Restart the Wildfly server with Hawtio:

    cd $WILDFLY_HOME/bin
    ./standalone.sh -Djboss.socket.binding.port-offset=101
  9. Access Hawtio at http://localhost:8181/hawtio. It is secured by Keycloak.