Using 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.16

  • 動作するコンテナランタイム(Docker, Podman)

  • 使用したい場合は、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

  • Keycloak

プロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

コマンドラインインタフェース
quarkus create app org.acme:security-keycloak-admin-client \
    --extension='keycloak-admin-rest-client,rest-jackson' \
    --no-code
cd security-keycloak-admin-client

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.40.1.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-keycloak-admin-client \
    -Dextensions='keycloak-admin-rest-client,rest-jackson' \
    -DnoCode
cd security-keycloak-admin-client

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=security-keycloak-admin-client"

このコマンドは、 keycloak-admin-rest-client エクステンションと rest-jackson エクステンションをインポートするプロジェクトを生成します。

Quarkus プロジェクトがすでに設定されている場合は、プロジェクトのベースディレクトリで次のコマンドを実行して、 keycloak-admin-rest-client エクステンションと rest-jackson エクステンションをプロジェクトに追加できます。

CLI
quarkus extension add keycloak-admin-rest-client,rest-jackson
Maven
./mvnw quarkus:add-extension -Dextensions='keycloak-admin-rest-client,rest-jackson'
Gradle
./gradlew addExtension --extensions='keycloak-admin-rest-client,rest-jackson'

これにより、ビルドファイルに次の内容が追加されます。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-keycloak-admin-rest-client</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>
build.gradle
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 を注入したい場合は、 quarkus.keycloak.admin-client.server-url が設定されていることが重要です。この設定プロパティーを設定せずに Keycloak を注入しようとすると、注入は失敗します。

アプリケーションコードで直接作成する代わりに Keycloak 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 は、他のレルムやクライアントを管理するように設定できます。認可が必要な Admin REST API を呼び出すためにアクセストークンを取得するには、 password または client_credentials グラントのいずれかを使用できます。

ユーザーのクレデンシャルをアクセストークンと交換する場合、 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 グラントタイプを使用します。
Note that the OidcClient can also be used to acquire tokens.

TLS の設定

Keycloak Admin Client の TLS 接続を設定するには、TLS Registry エクステンションを使用し、Keycloak Admin Client をそれぞれの 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 Admin Client を Keycloak に対してテストする推奨されるアプローチは、 Dev Services for Keycloak です。 Dev Services for Keycloak はテストコンテナーを起動して初期化します。その後、 quarkus レルムと quarkus-app クライアント (secret シークレット) を作成し、 alice (admin と user ロール) および bob (user ロール) ユーザーを追加します。これらのすべての設定プロパティーはカスタマイズ可能です。

たとえば、デフォルトでは、テストコンテナーはランダムに割り当てられたポートで利用可能ですが、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 Keycloak コンテナーがデフォルトで 45180 ポートをリッスンするように設定します
2 Keycloak Admin Client が同じポートを使用するように設定します

Quarkus Keycloak Admin Client 設定リファレンス

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

タイプ

デフォルト

Set to true if Keycloak Admin Client injection is supported.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_ENABLED

Show more

boolean

true

Keycloak server URL, for example, https://host:port. When the Keycloak Dev Services is started and this property is not configured, Quarkus points the 'quarkus.keycloak.admin-client.server-url' configuration property to started Keycloak container. In other cases, when this property is not set then the Keycloak Admin Client injection will fail - use org.keycloak.admin.client.KeycloakBuilder to create the client instead.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_SERVER_URL

Show more

string

Realm.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_REALM

Show more

string

master

Client id.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_ID

Show more

string

admin-cli

Client secret. Required with a client_credentials grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_SECRET

Show more

string

Username. Required with a password grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_USERNAME

Show more

string

admin

Password. Required with a password grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_PASSWORD

Show more

string

admin

OAuth 2.0 Access Token Scope.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_SCOPE

Show more

string

OAuth Grant Type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_GRANT_TYPE

Show more

password, client-credentials

password

The name of the TLS configuration to use.

If a name is configured, it uses the configuration from quarkus.tls.<name>.* If a name is configured, but no TLS configuration is found with that name then an error will be thrown.

The default TLS configuration is not used by default.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_TLS_CONFIGURATION_NAME

Show more

string