Keycloak Admin Clientの使用
Quarkus Keycloak Admin Clientとそのreactiveの2つは、実行中のKeycloakサーバーを設定するために使用できるKeycloak Admin Clientをサポートしています。
このガイドでは、 Quarkus ArC を活用して、Quarkusアプリケーションに管理者クライアントを注入する方法と、アプリケーションコードで直接作成する方法について説明します。
Keycloak Admin Clientの詳細については、 リファレンスガイド を参照してください。
前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 11+ がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.3
-
動作するコンテナランタイム(Docker, Podman)
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること
プロジェクトの作成
まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します:
Windowsユーザーの場合:
-
If using cmd, (don’t use backward slash
\
and put everything on the same line) -
If using Powershell, wrap
-D
parameters in double quotes e.g."-DprojectArtifactId=security-keycloak-admin-client"
このコマンドは、 keycloak-admin-client-reactive
と resteasy-reactive-jackson
のエクステンションをインポートするプロジェクトを生成します。
Quarkusプロジェクトをすでに設定している場合、プロジェクトのベースディレクトリで次のコマンドを実行することで、 keycloak-admin-client-reactive
と resteasy-reactive-jackson
のエクステンションをプロジェクトに追加することができます:
quarkus extension add 'keycloak-admin-client-reactive,resteasy-reactive-jackson'
./mvnw quarkus:add-extension -Dextensions='keycloak-admin-client-reactive,resteasy-reactive-jackson'
./gradlew addExtension --extensions='keycloak-admin-client-reactive,resteasy-reactive-jackson'
これにより、ビルドファイルに以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-keycloak-admin-client-reactive</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-resteasy-reactive-jackson</artifactId>
</dependency>
implementation("io.quarkus:quarkus-keycloak-admin-client-reactive")
implementation("io.quarkus:quarkus-resteasy-reactive-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.annotations.PostConstruct;
import jakarta.annotations.PreConstruct;
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 を使用することもできます。 |
Quarkus Keycloak Admin クライアント設定リファレンス
ビルド時に固定される設定プロパティ - その他の設定プロパティは実行時にオーバーライド可能です。
型 |
デフォルト |
|
---|---|---|
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 |
|
|