16.2. HawtIO における汎用 OpenID Connect 認証
HawtIO 4 は、既存の OpenID Connect プロバイダー (Keycloak、Microsoft Entra ID、Auth0 など) と併用でき、次のライブラリーを使用してタスクを実行します。
- HawtIO Server から OpenID Connect プロバイダーへの HTTP 通信を実装する Apache HTTP Client 4 (例: トークン署名検証用の公開鍵に関する情報を取得するため)。
- OpenID Connect/OAuth2 アクセストークンを操作および検証するための Nimbus JOSE + JWT ライブラリー。
これらのライブラリーは HawtIO Server WAR に含まれているため、追加のライブラリーをインストール/デプロイする必要はありません (Keycloak 固有の設定の場合と同様)。外部 OpenID Connect プロバイダーを使用して HawtIO を設定するには、1 つの設定ファイルを提供し、HawtIO をその場所に指す必要があります。
OIDC (OpenID Connect) 設定の場所を指定するシステムプロパティーは -Dhawtio.oidcConfig ですが、それが指定されていない場合はデフォルトの場所がチェックされます。デフォルトは次のとおりです。
-
Karaf ランタイムの場合:
${karaf.base}/etc/hawtio-oidc.properties -
Jetty ランタイムの場合:
${jetty.home}/etc/hawtio-oidc.properties -
Tomcat ランタイムの場合:
${catalina.home}/conf/hawtio-oidc.properties -
JBoss/EAP/Wildfly ランタイムの場合:
${jboss.server.config.dir}/hawtio-oidc.properties -
Apache Artemis ランタイムの場合:
${artemis.instance.etc}/hawtio-oidc.properties -
classpath:hawtio-oidc.propertiesにフォールバックします (組み込み HawtIO を使用する場合)
Keycloak 固有の設定とは異なり、1 つの *.properties ファイルで OpenID Connect 設定のすべてを設定できます。
以下はそのテンプレートです。
# OpenID Connect configuration requred at client side
# URL of OpenID Connect Provider - the URL after which ".well-known/openid-configuration" can be appended for
# discovery purposes
provider = http://localhost:18080/realms/hawtio-demo
# OpenID client identifier
client_id = hawtio-client
# response mode according to https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
response_mode = fragment
# scope to request when performing OpenID authentication. MUST include "openid" and required permissions
scope = openid email profile
# redirect URI after OpenID authentication - must also be configured at provider side
redirect_uri = http://localhost:8080/hawtio
# challenge method according to https://datatracker.ietf.org/doc/html/rfc7636
code_challenge_method = S256
# prompt hint according to https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
prompt = login
# additional configuration for the server side
# if true, .well-known/openid-configuration will be fetched at server side. This is required
# for proper JWT access token validation
oidc.cacheConfig = true
# time in minutes to cache public keys from jwks_uri
jwks.cacheTime = 60
# a path for an array of roles found in JWT payload. Property placeholders can be used for parameterized parts
# of the path (like for Keycloak) - but only for properties from this particular file
# example for properly configured Entra ID token
#oidc.rolesPath = roles
# example for Keycloak with use-resource-role-mappings=true
#oidc.rolesPath = resource_access.${client_id}.roles
# example for Keycloak with use-resource-role-mappings=false
oidc.rolesPath = realm_access.roles
# properties for role mapping. Each property with "roleMapping." prefix is used to map an original role
# from JWT token (found at ${oidc.rolesPath}) to a role used by the application
roleMapping.admin = admin
roleMapping.user = user
roleMapping.viewer = viewer
roleMapping.manager = manager
# timeout for connection establishment (milliseconds)
http.connectionTimeout = 5000
# timeout for reading from established connection (milliseconds)
http.readTimeout = 10000
# HTTP proxy to use when connecting to OpenID Connect provider
#http.proxyURL = http://127.0.0.1:3128
# TLS configuration (system properties can be used, e.g., "${catalina.home}/conf/hawtio.jks")
#ssl.protocol = TLSv1.3
#ssl.truststore = src/test/resources/hawtio.jks
#ssl.truststorePassword = hawtio
#ssl.keystore = src/test/resources/hawtio.jks
#ssl.keystorePassword = hawtio
#ssl.keyAlias = openid connect test provider
#ssl.keyPassword = hawtio
このファイルは、HawtIO および OpenID Connect の一部を設定します。
- OAuth2 - 認可サーバー、クライアント ID、いくつかの OpenID Connect 関連オプションの場所を設定します
- JWKS - jwks_uri から取得した公開鍵のキャッシュ時間。jwks_uri は、認可サーバーが使用する公開鍵を公開するエンドポイントです。
- JWT トークン設定 - 認証済みユーザーに関連付けられたロールを含むクレーム (JSON Web トークンのフィールド) に関する情報。また、認可サーバーで定義されたロールを、アプリケーション (HawtIO サーバーおよび Jolokia) で使用されるロールにマッピングすることもできます。
- HTTP 設定 - サーバー側の HTTP クライアントが認可サーバーに接続するため (OpenID Connect メタデータと公開された公開鍵を取得するため) に使用します。
この設定例は特定のニーズに合わせて調整できますが、そのままコンテナー化された Keycloak と組み合わせて使用しても機能します。以下を参照してください。