이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 13. OpenID Connect Integration
HawtIO is already supporting Keycloak as OpenID Provider. However, Keycloak already announced that the configuration methods used by HawtIO are deprecated. As OpenID Connect Core 1.0 is a widespread specification and standard method for distributed authentication (based on OAuth 2), HawtIO 4 now supports generic OpenID authentication.
13.1. Building blocks and terminology 링크 복사링크가 클립보드에 복사되었습니다!
To understand how HawtIO uses OpenID Connect and OAuth2, it is worth recalling some fundamental concepts. There are 3 main parties involved in distributed authentication based on OpenID Connect (which is build on OAuth2):
Resource Server:
The server component hosting protected resource(s), where access is restricted or granted based on access tokens. Usually this server is accessed through REST API and doesn’t provide user interface on its own.
Client:
The application (typically with user interface) that accesses resource server on behalf of a user (which is treated as resource owner). In order to access resource server it is mandatory for the client to obtain an access token first.
In OpenID Connect specification, the client is named relying party (RP).
Authorization Server:
The server that coordinates communication between a client and resource server. The client asks authorization server to authenticate the user (resource owner) and if the authentication succeeds, an access token is issued for the client to access resource server.
In OpenID Connect specification, the authorization server is named OpenID Provider (OP).
The main goal of OAuth2 and OpenID Connect it to allow applications to access APIs without using user credentials and switch to token exchange. It is important to know how HawtIO maps to the above roles:
- HawtIO Client application is an OAuth2 client. User interacts with Hawtio web application which in turn communicates with HawtIo Server (backend) with Jolokia agent running. Before accessing the Jolokia agent, HawtIO needs an OpenID Connect access token. To this end, HawtIO Client initiates OpenID Connect authentication process by redirecting user to Authorization Server.
- HawtIO Server application is a JakartaEE application exposing a Jolokia Agent API which authorizes user actions based on the content of an access token. Using OAuth2 terminology, HawtIO Server is a Resource Server.
The below UML diagram present the big picture.
The most important aspect is: HawtIO Client never deals with user credentials. User authenticates with Authorization Server and HawtIO Client only gets the access token used later to access Hawtio Server (and its Jolokia API).
13.2. Generic OpenID Connect authentication in HawtIO 링크 복사링크가 클립보드에 복사되었습니다!
HawtIO 4 can be used with existing OpenID Connect providers (like Keycloak, Microsoft Entra ID, Auth0, …) and uses these libraries to fullfill the task:
- Apache HTTP Client 4 to implement HTTP communication from Hawtio Server to OpenID Connect provider (e.g., to retrieve information about public keys for token signature validation).
- Nimbus JOSE + JWT library to manipulate and validate OpenID Connect / OAuth2 access tokens.
These libraries are included in HawtIO Server WAR, which means there’s no need to install/deploy any additional libraries (as it is the case with Keycloak specific configuration). In order to configure HawtIO with external OpenID Connect provider, we need to provide one configuration file and point HawtIO to its location.
The system property that specifies the location of OIDC (OpenID Connect) configuration is -Dhawtio.oidcConfig, but in case it’s not specified, a default location is checked. The defaults are:
-
For Karaf runtime,
${karaf.base}/etc/hawtio-oidc.properties -
For Jetty runtime,
${jetty.home}/etc/hawtio-oidc.properties -
For Tomcat runtime,
${catalina.home}/conf/hawtio-oidc.properties -
For JBoss/EAP/Wildfly runtime,
${jboss.server.config.dir}/hawtio-oidc.properties -
For Apache Artemis runtime,
${artemis.instance.etc}/hawtio-oidc.properties -
Falls back to
classpath:hawtio-oidc.properties(for embedded Hawtio usage)
Unlike with Keycloak specific configuration, there’s only one *.properties file needed that is used to configure all the aspects of OpenID Connect configuration.
Here’s the template:
This file configures several aspects of HawtIO+OpenID Connect:
- OAuth2 - configure the location of Authorization Server, client ID and several OpenID Connect related options
- JWKS - cache time for public keys obtained from jwks_uri, which is the endpoint that exposes public keys used by the Authorization Server.
- JWT token configuration - information about the claim (a field in JSON Web Token) that contains roles associated with the authenticated user. We also allow to map roles as defined in the Authorization Server to the roles used by the application (HawtIO Server and Jolokia).
- HTTP configuration - used by HTTP Client at server-side to connect to Authorization Server (to fetch OpenID Connect metadata and exposed public keys).
This example configuration can be adjusted to particular needs, but it also works as-is when used with containerized Keycloak. (See below).
13.3. JAAS role class configuration 링크 복사링크가 클립보드에 복사되었습니다!
OpenID Connect is used at HawtIO server side through JAAS. When HawtIO client obtains the access token, it is sent with every Jolokia request using HTTP Authorization: Bearer <access_token> header. Each role contained in the JWT token is (possibly after mapping) included as JAAS subject’s role principal. By default (when not configured explicitly) the class of role principal is io.hawt.web.auth.oidc.RolePrincipal.
However it is possible to configure another class (the requirement is - it has to contain single String-argument constructor) to be used as principal role class. For example, when used with Apache Artemis, the role should be org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal.
There’s a system property that specifies the role class:
-Dhawtio.rolePrincipalClasses=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal
-Dhawtio.rolePrincipalClasses=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal
13.4. Using HawtIO and OpenID Connect authentication with Keycloak 링크 복사링크가 클립보드에 복사되었습니다!
The simplest way to run Keycloak instance is using a container:
podman run -d --name keycloak \ -p 18080:8080 \ -e KEYCLOAK_ADMIN=admin \ -e KEYCLOAK_ADMIN_PASSWORD=admin \ quay.io/keycloak/keycloak:latest start-dev
podman run -d --name keycloak \
-p 18080:8080 \
-e KEYCLOAK_ADMIN=admin \
-e KEYCLOAK_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:latest start-dev
After it is started, browse to http://localhost:18080/admin/master/console/ and create a new realm:
At realm creation screen, upload hawtio-demo-realm.json which defines new hawtio-demo realm with pre-configured hawtio-client client and 3 users:
-
admin/admin with roles
manager,admin,vieweranduser -
viewer/viewer with roles
vieweranduser -
jdoe/jdoe with just
userrole
13.4.1. Investigating JWT token issues 링크 복사링크가 클립보드에 복사되었습니다!
In order to check the content of granted access token, we can use Keycloak interface. Navigate to "Clients", select "hawtio-client" and use "Client scopes" tab with "Evaluate" subtab:
Then in the "Users" field we can select for example "admin" and click "Generated access token". We can then examine an example token:
Knowing the structure of JWT access token we can check if role path is configured correctly:
example for Keycloak with use-resource-role-mappings=false
# example for Keycloak with use-resource-role-mappings=false
oidc.rolesPath = realm_access.roles
13.5. Using HawtIO and OpenID Connect authentication with Microsoft Entra ID 링크 복사링크가 클립보드에 복사되었습니다!
Hawtio 4 has also been tested with Microsoft Entra ID. While in theory, everything that should be required to use any OpenID Connect provider is to get access to relevant OpenID Provider Metadata, in practice we need some provider-specific configuration.
Clients are registered in Entra ID using "App registrations" blade. When registering an application, the most important decision is about a platform kind of the Redirect URI:
There are 2 options to choose from (we’re not considering "Public client/native (mobile & desktop)" platform). This UI is presented when configuring Redirect URIs later:
While it is not obvious what to choose at first glance, it is enough to state:
Web platform:
This kind of client is suitable for server-side applications and APIs.
SPA platform:
SPA applications are running within a browser where it’s natural to use "Authorization Code Flow" and so-called public client. The reason is that there’s no good way of storing credentials and secrets in browser application.
Choosing SPA platform gives us this mark in Entra ID UI:
13.5.1. Using single SPA client in Entra ID 링크 복사링크가 클립보드에 복사되었습니다!
After configuring the SPA client in Entra ID, we can already set relevant options in hawtio-oidc.properties. At "App registrations" blade in Entra ID we can click "Endpoints" tab and be presented with:
Tenant IDs are UUIDs specific to the Entra ID / Azure tenant being used. Here is the HawtIO configuration where provider is the base URL of your tenant and client_id is "Application (client) ID" from the Overview of App Registration page.
The problem with such configuration (where openid email profile is sent as a scope parameter) is that the assumed scope is in fact email openid profile User. Read and the granted access token is (showing only relevant JWT claims):
The aud (audience) claim is 00000003-0000-0000-c000-000000000000 which is an OAuth2 Client ID of … Microsoft Graph API.
Not only such access token should not be used by HawtIO server (with Jolokia agent), also the signature is created using keys associated with Microsoft Graph API.
In order to properly configure Entra ID and ensure that the access tokens generated are consumable by HawtIO Server, we need two app registrations - both for HawtIO Client and HawtIO Server. See the following subchapter.
13.5.2. Using SPA together with Web client in Entra ID 링크 복사링크가 클립보드에 복사되었습니다!
What is recommended is to set up two app registrations in Entra ID:
- An SPA client for Hawtio Client application - this is the way to configure an OAuth2 public client with PKCE enabled.
-
A Web (API) client for Hawtio Server application (in fact, its Jolokia API) - this is the Entra ID which exposes an API represented as scope named (for example)
api://hawtio-server/Jolokia.Access, which is then configured in the above Hawtio Client application as permitted API.
Finally, when the Authorization Code Flow is initiated one of the requested scopes in the scope parameter is the scope defined for HawtIO Server application (like api://hawtio-server/Jolokia.Access).
Let’s summarize the configuration required in Entra ID.
-
Create
hawtio-serverapp registration with "Web" Redirect URI. In "Expose an API" section, add a scope representing the access scope that may be requested from Hawtio Client:
This will create a reference’able
api://hawtio-server/Jolokia.Accessscope we will use later.In "App roles" section for
hawtio-serverdefine any roles you want to assign to users within the scope of this client, for example:In "Enterprise Applications" blade for
hawtio-servergo to "Users and groups" tab and add user-role assignment. For example:Create
hawtio-clientapp registration with "SPA" Redirect URI.In "API Permissions" section for
hawtio-clientapp registration, add a delegated permission forhawtio-serverexposed API:This should configure a set of delegated permissions similar to:
NoteRead more about delegated permissions in Microsoft Entra ID documentation.
-
No User-Role mapping is required for
hawtio-clientin Enterprise Application blade. Having the above configured, we can properly set the
scopeparameter in HawtIO configuration:This will create a reference’able
api://hawtio-server/Jolokia.Accessscope we will use later.-
In "App roles" section for
hawtio-serverdefine any roles you want to assign to users within the scope of this client, for example: -
In "Enterprise Applications" blade for
hawtio-servergo to "Users and groups" tab and add user-role assignment. For example: -
Create
hawtio-clientapp registration with "SPA" Redirect URI In "API Permissions" section for
hawtio-clientapp registration, add a delegated permission forhawtio-serverexposed API:This should configure a set of delegated permissions similar to:
NoteRead more about delegated permissions in Microsoft Entra ID documentation.
-
No User-Role mapping is required for
hawtio-clientin Enterprise Application blade.
Having the above configured, we can properly set the scope parameter in Hawtio configuration:
scope to request when performing OpenID authentication. MUST include "openid" and required permissions
# scope to request when performing OpenID authentication. MUST include "openid" and required permissions
scope = openid email profile api://hawtio-server/Jolokia.Access
13.5.3. Access token configuration 링크 복사링크가 클립보드에 복사되었습니다!
The final, but very important configuration item is the Token Configuration. For hawtio-server app registration, which is the app that represents Hawtio Server (and is the component that consumes granted access token) we have to ensure that groups claim is added to access token.
Here is the minimal configuration:
groups claim need to include security groups and directory roles and groups needs to be represented by names, not UUIDs:
For reference, here’s the relevant JSON snippet of hawtio-server app registration’s Manifest:
Now the granted access token is no longer specific for Microsft Graph API audience. It is intended for hawtio-server - aud claim is the UUID of hawtio-server app registration and appid claim is the UUID of hawtio-client app registration:
The roles which are then transformed (possibly with mapping) are available at roles claim and this is reflected in the configuration: