The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides
このページを編集

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）をインストールし、 適切に設定していること

  • 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.19.3: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 のエクステンションをプロジェクトに追加できます：

コマンドラインインタフェース
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をインジェクトすることは、よりシンプルで柔軟なオプションですが、必要であれば同じ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

型

デフォルト

quarkus.keycloak.admin-client.enabled

Set to true if Keycloak Admin Client injection is supported.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_ENABLED

Show more

boolean

true

quarkus.keycloak.admin-client.server-url

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

quarkus.keycloak.admin-client.realm

Realm.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_REALM

Show more

string

master

quarkus.keycloak.admin-client.client-id

Client id.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_ID

Show more

string

admin-cli

quarkus.keycloak.admin-client.client-secret

Client secret. Required with a client_credentials grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_CLIENT_SECRET

Show more

string

quarkus.keycloak.admin-client.username

Username. Required with a password grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_USERNAME

Show more

string

admin

quarkus.keycloak.admin-client.password

Password. Required with a password grant type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_PASSWORD

Show more

string

admin

quarkus.keycloak.admin-client.scope

OAuth 2.0 Access Token Scope.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_SCOPE

Show more

string

quarkus.keycloak.admin-client.grant-type

OAuth Grant Type.

Environment variable: QUARKUS_KEYCLOAK_ADMIN_CLIENT_GRANT_TYPE

Show more

password, client-credentials

password

quarkus.keycloak.admin-client.tls-configuration-name

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

参照

関連コンテンツ

同じトピックについて

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by