Keycloak Admin Clientの使用
Quarkus Keycloak Admin Clientとそのreactiveの2つは、実行中のKeycloakサーバーを設定するために使用できるKeycloak Admin Clientをサポートしています。
このガイドでは、 Quarkus ArC を活用して、Quarkusアプリケーションに管理者クライアントを注入する方法と、アプリケーションコードで直接作成する方法について説明します。
Keycloak Admin Clientの詳細については、 リファレンスガイド を参照してください。
前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 17+がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.9
-
動作するコンテナランタイム(Docker, Podman)
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること
プロジェクトの作成
まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。
Windowsユーザーの場合:
-
cmdを使用する場合、(バックスラッシュ
\
を使用せず、すべてを同じ行に書かないでください)。 -
Powershellを使用する場合は、
-D
パラメータを二重引用符で囲んでください。例:"-DprojectArtifactId=security-keycloak-admin-client"
このコマンドは、 keycloak-admin-rest-client
と rest-jackson
のエクステンションをインポートしたプロジェクトを生成します。
Quarkusプロジェクトがすでに設定されている場合は、プロジェクトのベースディレクトリで次のコマンドを実行することで、 keycloak-admin-rest-client
と rest-jackson
のエクステンションをプロジェクトに追加できます:
quarkus extension add keycloak-admin-rest-client,rest-jackson
./mvnw quarkus:add-extension -Dextensions='keycloak-admin-rest-client,rest-jackson'
./gradlew addExtension --extensions='keycloak-admin-rest-client,rest-jackson'
これにより、ビルドファイルに以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-keycloak-admin-rest-client</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-jackson</artifactId>
</dependency>
implementation("io.quarkus:quarkus-keycloak-admin-rest-client")
implementation("io.quarkus:quarkus-rest-jackson")
また、リクエストスコープのCDI Beanとして注入された Keycloak
を持つ単純なリソースが必要になってきます。
package org.acme.keycloak.admin.client;
import org.keycloak.admin.client.Keycloak;
import org.keycloak.representations.idm.RoleRepresentation;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.List;
@Path("/api/admin")
public class RolesResource {
@Inject
Keycloak keycloak; (1)
@GET
@Path("/roles")
public List<RoleRepresentation> getRoles() {
return keycloak.realm("quarkus").roles().list();
}
}
1 | 新しいレルム、クライアント、ユーザーの追加など、 admin-cli クライアントとしてKeycloak master レルム管理タスクを実行できるデフォルトのKeycloak Admin Clientを作成します。 |
このKeycloak Admin Clientを作成するために必要な設定は、KeycloakサーバーのURLのみです:
例えば、以下のようになります:
# Quarkus based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081
or
# WildFly based Keycloak distribution
quarkus.keycloak.admin-client.server-url=http://localhost:8081/auth
|
アプリケーションコードで直接作成する代わりにKeycloak Admin Clientをインジェクトすることは、よりシンプルで柔軟なオプションですが、必要であれば同じAdmin Clientを手動で作成することができます:
package org.acme.keycloak.admin.client;
import org.keycloak.admin.client.Keycloak;
import org.keycloak.admin.client.KeycloakBuilder;
import org.keycloak.representations.idm.RoleRepresentation;
import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.List;
@Path("/api/admin")
public class RolesResource {
Keycloak keycloak;
@PostConstruct
public void initKeycloak() {
keycloak = KeycloakBuilder.builder()
.serverUrl("http://localhost:8081")
.realm("master")
.clientId("admin-cli")
.grantType("password")
.username("admin")
.password("admin")
.build();
}
@PreDestroy
public void closeKeycloak() {
keycloak.close();
}
@GET
@Path("/roles")
public List<RoleRepresentation> getRoles() {
return keycloak.realm("quarkus").roles().list();
}
}
詳細については、 Keycloak Admin REST APIドキュメント を参照してください。
Keycloak Admin Clientは、他のレルムやクライアントを管理するように設定することができます。 password
または client_credentials
グラントを使用してアクセストークンを取得し、認証が必要なAdmin REST APIを呼び出すことができます。
ユーザーの認証情報をアクセストークンと交換する場合、 password
のグラントタイプの設定例を以下に示します:
quarkus.keycloak.admin-client.server-url=http://localhost:8081
quarkus.keycloak.admin-client.realm=quarkus
quarkus.keycloak.admin-client.client-id=quarkus-client
quarkus.keycloak.admin-client.username=alice
quarkus.keycloak.admin-client.password=alice
quarkus.keycloak.admin-client.grant-type=PASSWORD (1)
1 | password グラントタイプを使用する。 |
client-credentials
のグラントタイプを使用した例では、わずかな調整で済みます:
quarkus.keycloak.admin-client.enabled=true
quarkus.keycloak.admin-client.server-url=http://localhost:8081
quarkus.keycloak.admin-client.realm=quarkus
quarkus.keycloak.admin-client.client-id=quarkus-client
quarkus.keycloak.admin-client.client-secret=secret
quarkus.keycloak.admin-client.username= # remove default username
quarkus.keycloak.admin-client.password= # remove default password
quarkus.keycloak.admin-client.grant-type=CLIENT_CREDENTIALS (1)
1 | client_credentials グラントタイプを使用する。 |
なお、トークンの取得には OidcClient を使用することもできます。 |
TLS の設定
Keycloak管理クライアントにTLS接続を設定するには、TLSレジストリエクステンションを使用して、Keycloak管理クライアントにそれぞれのTLS設定を指定します。 例えば、次のように相互TLS(mTLS)を設定できます:
quarkus.keycloak.admin-client.tls-configuration-name=kc-mtls
quarkus.tls.kc-mtls.key-store.p12.path=client-keystore.p12
quarkus.tls.kc-mtls.key-store.p12.password=secret
quarkus.tls.kc-mtls.trust-store.p12.path=client-truststore.p12
quarkus.tls.kc-mtls.trust-store.p12.password=secret
テスト
Keycloakに対するKeycloak Admin Clientのテストには、 Dev Services for Keycloak を使用します。
Dev Services for Keycloak
はテストコンテナを起動して初期化します。そして、 quarkus
realmと quarkus-app
client ( secret
secret)を作成し、 alice
( admin
と user
role)と bob
( user
role)のユーザーを追加します。
例えば、デフォルトでは、テストコンテナはランダムに割り当てられたポートで利用可能ですが、以下のようにKeycloak Admin Clientとコンテナの両方が同じポートを使用するようにすることができます:
%test.quarkus.keycloak.devservices.port=${kc.admin.port.test:45180} (1)
%test.quarkus.keycloak.admin-client.server-url=http://localhost:${kc.admin.port.test:45180}/ (2)
1 | デフォルトで 45180 ポートをリッスンするようにKeycloakコンテナを設定します。 |
2 | 同じポートを使用するようにKeycloak Admin Clientを設定します。 |
Quarkus Keycloak Admin クライアント設定リファレンス
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
Set to true if Keycloak Admin Client injection is supported. Environment variable: Show more |
boolean |
|
Keycloak server URL, for example, Environment variable: Show more |
string |
|
Realm. Environment variable: Show more |
string |
|
Client id. Environment variable: Show more |
string |
|
Client secret. Required with a Environment variable: Show more |
string |
|
Username. Required with a Environment variable: Show more |
string |
|
Password. Required with a Environment variable: Show more |
string |
|
OAuth 2.0 Access Token Scope. Environment variable: Show more |
string |
|
OAuth Grant Type. Environment variable: Show more |
|
|
The name of the TLS configuration to use. If a name is configured, it uses the configuration from The default TLS configuration is not used by default. Environment variable: Show more |
string |