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.17.2: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"

This command generates a project which imports the keycloak-admin-rest-client and rest-jackson extensions.

If you already have your Quarkus project configured, you can add the keycloak-admin-rest-client and rest-jackson extensions to your project by running the following command in your project base directory:

コマンドラインインタフェース
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 の設定

To configure a TLS connection for the Keycloak Admin Client, use the TLS Registry extension and point the Keycloak Admin Client to respective TLS configuration. For example, you can configure mutual TLS (mTLS) like this:

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

テスト

The preferred approach for testing Keycloak Admin Client against Keycloak is Dev Services for Keycloak. Dev Services for Keycloak will start and initialize a test container. Then, it will create a quarkus realm and a quarkus-app client (secret secret) and add alice (admin and user roles) and bob (user role) users, where all of these properties can be customized.

For example, by default, a test container will be available at a randomly allocated port but you can make both Keycloak Admin Client and the container use the same port as follows:

%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 Configure the Keycloak container to listen on the 45180 port by default
2 Configure the Keycloak Admin Client to use the same port

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

参照

関連コンテンツ

On the same topics

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

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

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