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 およびそのリアクティブ版は、実行中の Keycloak サーバーを設定するために使用できる Keycloak Admin Client をサポートしています。

このガイドでは、 Quarkus ArC を活用して、管理クライアントを Quarkus アプリケーションに注入する方法と、アプリケーションコードで直接作成する方法について説明します。

Keycloak Admin Client の詳細については、 リファレンスガイド を参照してください。

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.9.12

  • 動作するコンテナランタイム(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.34.6: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

または

# 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 グラントタイプを使用します。
なお、 OidcClient もトークンの取得に使用できます。

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

型

デフォルト

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 または互換性のあるライセンスの下で利用可能です。 CC by 3.0

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

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. 全著作権所有。当社の商標の詳細については、商標ポリシーおよび商標リストをご覧ください。第三者の商標は、それぞれの所有者に帰属し、ここに記載されていることは、いかなる推奨や関連も示唆するものではありません。