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

OpenID Connect (OIDC)のDev ServicesとDev UI

Dev Services for Keycloak と OpenID Connect (OIDC) Keycloak プロバイダー用の Dev UI を使用して、これらのサービスを他の OpenID Connect プロバイダーに適応させることができます。 Quarkus を開発モードで実行する前に、すでに起動している OpenID Connect プロバイダーで Dev UI を使用することもできます。

はじめに

Quarkus には、Dev Services for Keycloak 機能があります。この機能は、quarkus-oidc エクステンションが開発モードで起動され、結合テストがテストモードで実行され、 quarkus.oidc.auth-server-url プロパティーが設定されていない場合にデフォルトで有効になります。 Dev Services for Keycloak 機能は、開発モードとテストモードの両方で Keycloak コンテナーを起動します。 Keycloak で保護された Quarkus アプリケーションの開発をすぐに開始するために必要なクライアントとユーザーを含む既存の Keycloak レルムを登録するか、新しいレルムを作成することで、コンテナーを初期化します。 application.properties またはレルムファイルの変更が検出されると、コンテナーが再起動します。

さらに、http://localhost:8080/q/dev-ui/extensions[/q/dev-ui/extensions] で入手可能な Dev UI は、Keycloak からトークンを取得して Quarkus アプリケーションをテストするのに役立つ Dev UI ページでこの機能を補完します。

quarkus.oidc.auth-server-url がすでに設定されている場合、すべての OpenID Connect プロバイダーで使用できる汎用の OpenID Connect Dev Console がアクティブになります。 詳細は、Dev UI for all OpenID Connect providers を参照してください。

Dev Services for Keycloak

application.properties ファイルで quarkus.oidc プロパティーを設定せずにアプリケーションを起動します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

コンソールに次のような出力が表示されます。

KeyCloak Dev Services Starting:
2021-11-02 17:14:24,864 INFO  [org.tes.con.wai.str.HttpWaitStrategy] (build-10) /unruffled_agnesi: Waiting for 60 seconds for URL: http://localhost:32781 (where port 32781 maps to container port 8080)
2021-11-02 17:14:44,170 INFO  [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-10) Dev Services for Keycloak started.

Keycloak 管理コンソールにログインする場合、ユーザー名は admin、パスワードは admin です。

Dev Services for Keycloak は、quarkus-dev-service-keycloak というラベルの付いた既存のコンテナーを検出した場合、デフォルトで新しいコンテナーを起動しないことに注意してください。 quarkus.keycloak.devservices.service-name プロパティーの値がラベルの値 (デフォルトは quarkus) と一致する場合、このコンテナーに接続します。 このような場合、以下を実行すると出力が若干変更されることがあります。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev
2021-08-27 18:42:43,530 INFO  [io.qua.dev.com.ContainerLocator] (build-15) Dev Services container found: 48fee151a31ddfe32c39965be8f61108587b25ed2f66cdc18bb926d9e2e570c5 (quay.io/keycloak/keycloak:21.0.2). Connecting to: 0.0.0.0:32797.
2021-08-27 18:42:43,600 INFO  [io.qua.oid.dep.dev.key.KeycloakDevServicesProcessor] (build-15) Dev Services for Keycloak started.
...

Keycloak コンテナーがデフォルトの 60 秒のタイムアウト内に準備できない場合は、タイムアウト期間を延長することで解決できます。 たとえば、quarkus.devservices.timeout=2M で 2 分に設定します。

quarkus.keycloak.devservices.shared=false を指定すると、コンテナーの共有をオフにすることができます。

次に、メインの Dev UI ページ を開き、Keycloak ページにリンクしている OpenID Connect カードを確認します。 次に例を示します。

Dev UI OpenID Connect card

Keycloak provider リンクをクリックします。 このアクションにより、Dev Services for Keycloak 機能の設定に応じて外観が異なる Keycloak ページが開きます。

サービスアプリケーションの開発

デフォルトでは、Keycloak ページを使用して、Quarkus OIDC サービスアプリケーション の開発をサポートできます。

認可コードグラント

application.properties ファイルで quarkus.oidc.devui.grant.type=code を設定すると (これがデフォルト値です)、アクセストークンと ID トークンの両方を取得するために authorization_code グラントが使用されます。 シングルページアプリケーション (SPA) でトークンを取得し、それを使用して Quarkus サービスにアクセスする一般的なフローをエミュレートするには、このグラントを使用することを推奨します。

まず、Log into Single Page Application オプションが表示されます。 次に例を示します。

Dev UI OpenID Connect Keycloak Page - Log into Single Page Application

認証プロセス中に使用する Keycloak レルムとクライアント ID を選択します。

この SPA は、OpenId Connect の public クライアントを表します。したがって、入力するクライアント ID は、シークレットのない Keycloak の public クライアントを指す必要があります。 これは、SPA が Web アプリケーションではないため、クライアントシークレットも認可コードフローを完了することが予想される場合、認可コードフローを完了するために必要なクライアントシークレットを安全に扱うことができないためです。

シークレットが必要なクライアントは、デフォルトのレルムが作成されている場合、または quarkus.oidc.credentials.secret が設定されていて単一のカスタムレルムが使用されている場合にのみ、この SPA でサポートできます。 どちらの場合も、Keycloak がユーザーを SPA にリダイレクトした後、SPA は認可コードフローを完了するために必要なクライアントシークレットを把握できます。

次に、Log into Single Page Application を選択すると、Keycloak にリダイレクトされ、たとえば alice:alice として認証されます。 次に、SPA を表すページに戻ります。

Dev UI OpenID Connect Keycloak Single Page Application

取得したアクセストークンやIDトークンなどを確認することができます。

Dev UI OpenID Connect Keycloak Decoded Tokens View

このビューでは、エンコードされた JSON Web Token (JWT) トークンが左側に表示され、ヘッダーが赤で、ペイロードまたはクレームが緑で、署名が青で強調表示されます。 また、右側にはデコードされた JWT トークンが表示され、ヘッダー、クレーム名、およびそれらの値を確認できます。

次に、相対サービスパスを入力し、トークンを送信してサービスをテストします。 SPAは通常、アプリケーションのエンドポイントにアクセストークンを送信するので、たとえば With Access Token オプションを選択します。

Dev UI Keycloak - With Access Token

テスト結果領域を消去するには、右下隅にある消しゴムアイコンを使用します。

場合によっては、ID トークンがベアラートークンとしてアプリケーションフロントエンドに転送されることがあります。 これにより、エンドポイントが SPA にログインしているユーザーを識別したり、帯域外のトークン検証を実行したりできるようになります。 このような場合は、With ID Token オプションを選択してください。

カスタム Keycloak レルムをインポートする場合、Dev UI でアクセストークンと ID トークンの両方を検査した後、アクセストークンのみに groups クレームのロールのリストが含まれていることがわかります。 この情報は、@RolesAllowed アノテーションで保護されたエンドポイントにアクセスする際に重要です。 Keycloak にこの情報を ID トークンに含めるように指示するには、Keycloak 管理コンソールのクライアントスコープのリストに microprofile-jwt スコープを追加します。 または、quarkus.oidc.authentication.scopes プロパティーを使用して、必要なスコープのリストに microprofile-jwt スコープを追加します。

詳細は、https://www.keycloak.org/docs/latest/server_admin/#protocol[Keycloak サーバー管理ガイド] を参照してください。

サービスパスを手動で入力するのは理想的ではありません。 OIDC Dev UI ですでに取得済みのアクセストークンを使用してサービスをテストするために Swagger または GraphQL UI を有効にする方法については、Test with Swagger UI or GraphQL UI セクションを参照してください。

最後に、Log Out image::dev-ui-keycloak-logout.png[alt=Dev UI Keycloak - Log Out,role="center"] をクリックすると、別のユーザーとして Keycloak に認証できるようになります。

Log into Single Page Application を選択しすると、Keycloak からエラーが返される場合があります。 たとえば、quarkus.oidc.client-id が Keycloak にインポートされたレルム内のクライアント ID と一致しない可能性があります。または、このレルム内のクライアントが認可コードフローをサポートするように正しく設定されていない可能性があります。 このような場合、Keycloak は error_description クエリーパラメーターを返し、Dev UI にもこのエラーの説明が表示されます。 次に例を示します。

Dev UI Keycloak Login Error

エラーが発生した場合は、Keycloak Admin オプションを使用して Keycloak にログインし、必要に応じてレルム設定を更新し、application.properties を確認してください。

Swagger UI または GraphQL UI を使用したテスト

プロジェクトで quarkus-smallrye-openapi または quarkus-smallrye-graphql が使用されている場合は、サービスパスを手動で入力する必要がなくなり、Swagger UI または GraphQL UI を使用してサービスをテストできます。 たとえば、quarkus-smallrye-openapiquarkus-smallrye-graphql の両方の依存関係を使用して Quarkus を開発モードで起動します。 Keycloak にログインすると、次のオプションが表示されます。

Test your service with Swagger UI or GraphQL UI

たとえば、Swagger UI をクリックすると、新しいブラウザータブで Swagger UI が開き、Keycloak 用の Dev UI によって取得されたトークンを使用してサービスをテストできます。 Swagger UI は再度認証を試行しません。 Swagger UI で、Swagger UI の Authorize オプションを選択しないでください。OIDC Dev UI が Swagger UI を認可し、テストに使用するアクセストークンを提供しているためです。

GraphQL UI とのインテグレーションも同様に機能し、Keycloak 用の Dev UI によって取得されたアクセストークンが使用されます。

Keycloak 用の Dev UI によって開始される認可コードフローを機能させるには、リダイレクト URI を登録する必要がある場合があります。 Keycloak は、認証されたユーザーが設定されたリダイレクト URI にのみリダイレクトされるように強制する場合があるためです。 認証リクエスト内の正しい redirect_uri パラメーターが操作されると、ユーザーが間違ったエンドポイントにリダイレクトされる可能性があるため、本番環境ではこれを行うことを推奨します。

Keycloak がそれを強制する場合、redirect_uri 値が間違っていることを通知する認証エラーが表示されます。

この場合、右上隅の Keycloak Admin オプションを選択し、admin:admin としてログインし、テストレルムと、Keycloak 用の Dev UI が設定されているクライアントを選択し、http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/keycloak-providerValid Redirect URIs に追加します。 Quarkus の起動時に -Dquarkus.http.port を使用した場合は、8080quarkus.http.port の値に変更します。

異なるポートで実行されている複数のアプリケーション間でコンテナーを共有する場合は、アプリケーションごとに redirect_uri 値を登録する必要があります。

特にコンテナーが複数のアプリケーション間で共有されている場合は、テスト目的でのみ redirect_uri 値を * に設定できます。

カスタムレルムがインポートされていない場合、Dev Services for Keycloak はデフォルトのレルムを作成するときに redirect_uri 値を * に設定します。

インプリシット・グラント

application.properties ファイルで quarkus.oidc.devui.grant.type=implicit を設定すると、アクセストークンと ID トークンの両方を取得するために implicit グラントが使用されます。 認可コードグラントが機能しない場合 (インプリシットグラントをサポートするためにクライントが Keycloak に設定されている場合) に限り、このグラントを使用してシングルページアプリケーションをエミュレートします。

パスワード・グラント

application.properties ファイルで quarkus.oidc.devui.grant.type=password を設定すると、次のような画面が表示されます。

Dev UI OpenID Connect Keycloak Page - Password Grant

レルムを選択し、クライアント ID とシークレット、ユーザー名とパスワード、相対サービスエンドポイントパスを入力して、Test service をクリックします。 200403401404 などのステータスコードが返されます。 ユーザー名とパスワードを含む quarkus.keycloak.devservices.users マッププロパティーにもユーザー名が設定されている場合は、サービスをテストするときにパスワードを設定する必要はありません。 password グラントを使用してサービスをテストするために、quarkus.keycloak.devservices.users を初期化する必要はないことに注意してください。

Dev UI コンソールでは、次のような出力も表示されます。

2021-07-19 17:58:11,407 INFO  [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Using password grant to get a token from 'http://localhost:32818/realms/quarkus/protocol/openid-connect/token' for user 'alice' in realm 'quarkus' with client id 'quarkus-app'
2021-07-19 17:58:11,533 INFO  [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Test token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6Z2tDazJQZ1JaYnVlVG5kcTFKSW1sVnNoZ2hhbWhtbnBNcXU0QUt5MnJBIn0.ey...
2021-07-19 17:58:11,536 INFO  [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Sending token to 'http://localhost:8080/api/admin'
2021-07-19 17:58:11,674 INFO  [io.qua.oid.dep.dev.key.KeycloakDevConsolePostHandler] (security-openid-connect-quickstart-dev.jar) (DEV Console action) Result: 200

トークンは password グラントを使用して Keycloak から取得され、サービスエンドポイントに送信されます。

クライアントクレデンシャル・グラント

quarkus.oidc.devui.grant.type=client を設定すると、トークンの取得に client_credentials グラントが使用されます。この場合、ページに User フィールドは表示されません。

Dev UI OpenID Connect Keycloak Page - Client Credentials Grant

レルムを選択し、クライアント ID とシークレット、相対サービスエンドポイントパスを入力して、Test service をクリックします。 200403401404 などのステータスコードが返されます。

OpenID Connectウェブアプリケーション開発

Quarkus OIDCウェブアプリケーション を開発するには、アプリケーションを開始する前に、 application.properties ファイルで quarkus.oidc.application-type=web-app を設定します。

アプリケーションを起動すると、このような画面が表示されます:

Dev UI OpenID Connect Keycloak Sign In

相対的なサービスエンドポイントパスを設定し、Log in to your web application をクリックします。 Quarkus アプリケーションからのレスポンスを受け取る前に、新しいブラウザータブでユーザー名とパスワードを入力するために Keycloak にリダイレクトされます。

テストの実行

テストモードで起動した Keycloak コンテナーに対して、継続的テスト モードでテストを実行できます。

また、Dev Services for Keycloak を使用して、Keycloak に対して結合テストを実行することを推奨します。 詳細は、Dev Services を使用した OpenID Connect サービスアプリケーションのテスト および Dev Services を使用した OpenID Connect WebApp アプリケーションのテスト を参照してください。

Keycloak 初期化

デフォルトでは、Quarkus を搭載した Keycloak ディストリビューションを含む quay.io/keycloak/keycloak:26.1.3 イメージがコンテナーの起動に使用されます。 quarkus.keycloak.devservices.image-name を使用して、Keycloak イメージ名を変更できます。 たとえば、WildFly を搭載した Keycloak ディストリビューションを使用するには、quay.io/keycloak/keycloak:19.0.3-legacy に設定します。 Quarkus ベースの Keycloak ディストリビューションは、Keycloak 20.0.0 以降でのみ使用できることに注意してください。

Dev Services for Keycloakは、起動したKeycloakサーバーを次に初期化します。

デフォルトでは、パスワードが secretquarkus および quarkus-app クライアント、alice および bob ユーザー (パスワードは名前と同じ)、user および admin ロールが作成されます。このとき、alice には adminuser の両方のロールが与えられ、bob には user ロールが与えられます。

ユーザー名、シークレット、およびそれらのロールは、quarkus.keycloak.devservices.users (ユーザー名とシークレットを含むマップ) および quarkus.keycloak.devservices.roles (ユーザー名とコンマ区切りのロール値を含むマップ) でカスタマイズできます。

例:

%dev.quarkus.keycloak.devservices.users.duke=dukePassword
%dev.quarkus.keycloak.devservices.roles.duke=reader
%dev.quarkus.keycloak.devservices.users.john=johnPassword
%dev.quarkus.keycloak.devservices.roles.john=reader,writer

この設定により、2人のユーザーが作成されます: * dukePassword パスワードと reader ロールを持つ duke * johnPassword パスワードと reader および writer ロールを持つ john

クライアント ID とシークレットをカスタマイズするには、quarkus.oidc.client-id プロパティーと quarkus.oidc.credentials.secret プロパティーを使用できます。

ただし、Keycloak の設定がより複雑になり、より多くのプロパティーの設定が必要になる可能性があります。

このため、Keycloak をデフォルトまたは設定されたレルム、クライアント、ユーザー、およびロールのプロパティーで初期化する前に、常に quarkus.keycloak.devservices.realm-path がチェックされます。 realm ファイルがファイルシステムまたはクラスパス上に存在する場合、この realm だけが Keycloak を初期化するために使用されます。次に例を示します。

quarkus.keycloak.devservices.realm-path=quarkus-realm.json

quarkus.keycloak.devservices.realm-path を使って、カンマで区切られたファイルのリストを提供することで、複数のレルムファイルでKeycloakを初期化することができます:

quarkus.keycloak.devservices.realm-path=quarkus-realm1.json,quarkus-realm2.json

また、Keycloak ページには、右上隅にある Keycloak Admin オプションを使用して、Keycloak にサインインしてレルムを設定するオプション (Sign In To Keycloak To Configure Realms) があります。

Dev UI OpenID Connect Keycloak Page - Keycloak Admin

レルムのプロパティーのカスタマイズ、新規レルムの作成またはインポート、レルムのエクスポートを実行するには、Keycloak に admin:admin としてサインインします。

クラスパスとファイルシステムリソースをコンテナーにコピーすることもできます。 たとえば、jar ファイルで Keycloak にデプロイされる JavaScript ポリシー を使用してアプリケーションが Keycloak 認証を設定する場合、次のようにしてこの jar を Keycloak コンテナーにコピーするように Dev Services for Keycloak を設定できます。

quarkus.keycloak.devservices.resource-aliases.policies=/policies.jar (1)
quarkus.keycloak.devservices.resource-mappings.policies=/opt/keycloak/providers/policies.jar (2)
1 クラスパス /policies.jar リソースに対して policies エイリアスが作成されます。

ポリシー jar はファイルシステム内に配置することもできます。 <2> ポリシー jar は、/opt/keycloak/providers/policies.jar コンテナーの場所にマップされます。

Dev Services for Keycloak を無効にする

quarkus.oidc.auth-server-url がすでに初期化されているか、デフォルトの OIDC テナントが quarkus.oidc.tenant.enabled=false で無効になっている場合、Keycloak を使用するかどうかにかかわらず、Dev Services For Keycloak はアクティブ化されません。

Dev Services for Keycloak コンテナーを起動させない、または使用しない場合も、quarkus.keycloak.devservices.enabled=false を使用してこの機能を無効化できます。これは、quarkus.oidc.auth-server-url なしで quarkus:dev を起動する予定がある場合にのみ必要です。

Dev Services for Keycloak が無効になっていて、quarkus.oidc.auth-server-url プロパティーが初期化されていない場合、メインの Dev UI ページに空の OpenID Connect カードが表示されます。

Dev UI OpenID Connect card

quarkus.oidc.auth-server-url がすでに設定されている場合は、すべての OpenID Connect プロバイダーで使用できる汎用の OpenID Connect Dev Console をアクティブ化できます。詳細は、Dev UI for all OpenID Connect providers セクションを参照してください。

すべてのOpenID ConnectプロバイダーのためのDev UI

以下の条件を満たす場合、すべての OpenID Connect プロバイダーの Dev UI が有効になります:

  • quarkus.oidc.auth-server-url が、すでに起動している OpenID Connect プロバイダー (Keycloak またはその他のプロバイダー) を指している。

  • quarkus.oidc.application-type が、デフォルト値の service または hybrid に設定されている。

  • quarkus.oidc.client-id が設定されている。

quarkus.oidc.client-id で識別されるクライアントが OpenID Connect プロバイダーの管理コンソールで public クライアントとして設定されていない限り、Dev UI から開始された認可コードフローを完了するには、おそらく Keycloak やその他のプロバイダーで quarkus.oidc.credentials.secret を設定する必要があります。

たとえば、Dev UI を使用して、次の設定で Google 認証をテストできます。

quarkus.oidc.provider=google
quarkus.oidc.application-type=hybrid
quarkus.oidc.client-id=${google-client-id}
quarkus.oidc.credentials.secret=${google-client-secret}

以下を実行します。

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

このコマンドは、次の例のようなメッセージを出力します。

...
2021-09-07 15:53:42,697 INFO  [io.qua.oid.dep.dev.OidcDevConsoleProcessor] (build-41) OIDC Dev Console: discovering the provider metadata at https://accounts.google.com/.well-known/openid-configuration
...

プロバイダーメタデータの検出が成功した場合、メインの Dev UI ページ を開くと、Google プロバイダーを参照する次の OpenID Connect カードが表示されます。

Generic Dev UI OpenID Connect card

リンクをたどってプロバイダーにログインし、トークンを取得して、アプリケーションをテストします。 特に Keycloakを使用している場合、これは Dev Services for Keycloak コンテナーを起動した Authorization code grant for Keycloak セクションの説明のとおりです。

多くの場合、Dev Console へのリダイレクトをサポートするように OpenID Connect プロバイダーを設定する必要があります。 http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/<providerName>-provider を、サポートされているリダイレクトおよびログアウト URL の 1 つとして追加します。<providerName> ` は、Dev UI に表示されるプロバイダーの名前 (例: `auth0) に置き換える必要があります。

他のプロバイダーを使用している場合、Authorization code grant for Keycloak で説明されている Dev UI のエクスペリエンスが若干異なる場合があります。 たとえば、アクセストークンが JWT 形式でない場合、その内部コンテンツを表示できません。 ただし、すべてのプロバイダーが JWT 形式で ID トークンを返すはずです。

現在のアクセストークンは、Swagger UI または GrapghQL UI でサービスをテストするためにデフォルトで使用されます。 プロバイダー (Keycloak 以外) がバイナリーアクセストークンを返す場合、このプロバイダーにトークンイントロスペクションエンドポイントがある場合にのみ、Swagger UI または GrapghQL UI で使用されます。それ以外の場合は、常に JWT 形式の IdToken が Swagger UI または GrapghQL UI に渡されます。 このような場合、手動の Dev UI テストを使用して、現在のバイナリーアクセストークンに対して常に 401 が返されることを確認できます。 また、これらのいずれかのユーザーインターフェイスで IdToken をフォールバックとして使用することは、認可コードフローでのみ可能であることに注意してください。

Auth0 などの一部のプロバイダーは、標準の RP 起点のログアウトをサポートしていないため、ログアウトオプションを表示するには、プロバイダー固有のログアウトプロパティーを設定する必要があります。 詳細は、「Web アプリケーションを保護するための OpenID Connect 認可コードフローメカニズム」ガイドの ユーザー起点のログアウト セクションを参照してください。

同様に、Dev UI に password または client_credentials グラントを使用してトークンを取得する場合は、プロバイダー固有の追加のプロパティーを設定する必要がある場合があります。次に例を示します。

quarkus.oidc.devui.grant.type=password
quarkus.oidc.devui.grant-options.password.audience=http://localhost:8080

アプリケーション以外のルートパスに関する考慮事項

このドキュメントでは、いくつかの場所で Dev UI URL を http://localhost:8080/q/dev-ui と表記しています。q は、デフォルトのアプリケーション以外のルートパスです。 quarkus.http.root-path または quarkus.http.non-application-root-path プロパティーをカスタマイズする場合は、それに応じて q を置き換えてください。 詳細は、ブログ記事の Path resolution in Quarkus を参照してください。

Dev Services for OIDC

Keycloak を実稼働環境で使用する場合、Dev Services for Keycloak 最高の開発モードエクスペリエンスを提供します。 他の OpenID Connect プロバイダーの場合は、次の例のように OIDC の Dev Services を有効にすることを推奨します。

quarkus.oidc.devservices.enabled=true
Docker と Podman が利用できない場合は、OIDC の開発サービスがデフォルトで有効になります。

有効にすると、Quarkus は最も一般的な OpenID Connect 操作をサポートする新しい OIDC サーバーを起動します。 OIDC サーバーが起動したことをコンソールで確認すると、次のような出力が表示されます。

2025-01-08 20:50:20,900 INFO  [io.qua.dev.oid.OidcDevServicesProcessor] (build-16) Dev Services for OIDC started on http://localhost:38139

すべてのOpenID ConnectプロバイダーのためのDev UI に移動すると、組み込みユーザー alice または bob として OIDC サーバーにログインできます。

Dev Services for OIDC builtin user login

このログインページは、Quarkus OIDC Web アプリケーション の開発中に認証されたリクエストパスに移動した場合にも表示されます。 いつものように、alice のデフォルトのロールは adminuser ですが、bob のロールは user のみです。 必要に応じて、これらの組み込みロールを設定できます。

quarkus.oidc.devservices.roles.alice=root (1)
quarkus.oidc.devservices.roles.bob=guest
1 ユーザー aliceroot ロールを割り当てます。

もう 1 つのオプションとして、選択したユーザー名とロールを持つカスタムユーザーとしてログインします。

Dev Services for OIDC custom user login

どちらのユーザーを選択しても、パスワードは必要ありません。

設定リファレンス

ビルド時に固定された設定プロパティー。その他の設定プロパティーは、すべて実行時にオーバーライド可能です。

Configuration property

デフォルト

Flag to enable (default) or disable Dev Services. When enabled, Dev Services for Keycloak automatically configures and starts Keycloak in Dev or Test mode, and when Docker is running.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_ENABLED

Show more

boolean

true

The container image name for Dev Services providers. Defaults to a Quarkus-based Keycloak image. For a WildFly-based distribution, use an image like quay.io/keycloak/keycloak:19.0.3-legacy. Keycloak Quarkus and WildFly images are initialized differently. Dev Services for Keycloak will assume it is a Keycloak Quarkus image unless the image version ends with -legacy. Override with quarkus.keycloak.devservices.keycloak-x-image.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_IMAGE_NAME

Show more

string

quay.io/keycloak/keycloak:26.1.3

Indicates if a Keycloak-X image is used. By default, the image is identified by keycloak-x in the image name. For custom images, override with quarkus.keycloak.devservices.keycloak-x-image. You do not need to set this property if the default check works.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_KEYCLOAK_X_IMAGE

Show more

boolean

Determines if the Keycloak container is shared. When shared, Quarkus uses label-based service discovery to find and reuse a running Keycloak container, so a second one is not started. Otherwise, if a matching container is not is found, a new container is started. The service discovery uses the quarkus-dev-service-label label, whose value is set by the service-name property. Container sharing is available only in dev mode.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_SHARED

Show more

boolean

true

The value of the quarkus-dev-service-keycloak label for identifying the Keycloak container. Used in shared mode to locate an existing container with this label. If not found, a new container is initialized with this label. Applicable only in dev mode.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_SERVICE_NAME

Show more

string

quarkus

A comma-separated list of class or file system paths to Keycloak realm files. This list is used to initialize Keycloak. The first value in this list is used to initialize default tenant connection properties.

To learn more about Keycloak realm files, consult the Importing and Exporting Keycloak Realms documentation.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_REALM_PATH

Show more

list of string

Aliases to additional class or file system resources that are used to initialize Keycloak. Each map entry represents a mapping between an alias and a class or file system resource path.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_RESOURCE_ALIASES__ALIAS_NAME_

Show more

Map<String,String>

Additional class or file system resources that are used to initialize Keycloak. Each map entry represents a mapping between a class or file system resource path alias and the Keycloak container location.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_RESOURCE_MAPPINGS__RESOURCE_NAME_

Show more

Map<String,String>

The JAVA_OPTS passed to the keycloak JVM

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_JAVA_OPTS

Show more

string

Show Keycloak log messages with a "Keycloak:" prefix.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_SHOW_LOGS

Show more

boolean

false

Keycloak start command. Use this property to experiment with Keycloak start options, see https://www.keycloak.org/server/all-config. Note, it is ignored when loading legacy Keycloak WildFly images.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_START_COMMAND

Show more

string

Keycloak features. Use this property to enable one or more experimental Keycloak features. Note, if you also have to customize a Keycloak start-command(), you can use a --features option as part of the start command sequence, instead of configuring this property.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_FEATURES

Show more

list of string

The name of the Keycloak realm. This property is used to create the realm if the realm file pointed to by the realm-path property does not exist. The default value is quarkus in this case. It is recommended to always set this property so that Dev Services for Keycloak can identify the realm name without parsing the realm file.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_REALM_NAME

Show more

string

Specifies whether to create the Keycloak realm when no realm file is found at the realm-path. Set to false if the realm is to be created using either the Keycloak Administration Console or the Keycloak Admin API provided by io.quarkus.test.common.QuarkusTestResourceLifecycleManager.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_CREATE_REALM

Show more

boolean

true

Specifies whether to create the default client id quarkus-app with a secret secret and register them if the create-realm property is set to true. For OIDC extension configuration properties quarkus.oidc.client.id and quarkus.oidc.credentials.secret will be configured. For OIDC Client extension configuration properties quarkus.oidc-client.client.id and quarkus.oidc-client.credentials.secret will be configured. Set to false if clients have to be created using either the Keycloak Administration Console or the Keycloak Admin API provided by io.quarkus.test.common.QuarkusTestResourceLifecycleManager or registered dynamically.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_CREATE_CLIENT

Show more

boolean

true

Specifies whether to start the container even if the default OIDC tenant is disabled. Setting this property to true may be necessary in a multi-tenant OIDC setup, especially when OIDC tenants are created dynamically.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_START_WITH_DISABLED_TENANT

Show more

boolean

false

A map of Keycloak usernames to passwords. If empty, default users alice and bob are created with their names as passwords. This map is used for user creation when no realm file is found at the realm-path.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_USERS__USERS_

Show more

Map<String,String>

A map of roles for Keycloak users. If empty, default roles are assigned: alice receives admin and user roles, while other users receive user role. This map is used for role creation when no realm file is found at the realm-path.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_ROLES__ROLE_NAME_

Show more

Map<String,List<String>>

The specific port for the dev service to listen on.

If not specified, a random port is selected.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_PORT

Show more

int

Environment variables to be passed to the container.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_

Show more

Map<String,String>

Memory limit for Keycloak container

If not specified, 750MiB is the default memory limit.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_CONTAINER_MEMORY_LIMIT

Show more

MemorySize 

750M

The WebClient timeout. Use this property to configure how long an HTTP client used by OIDC dev service admin client will wait for a response from OpenId Connect Provider when acquiring admin token and creating realm.

Environment variable: QUARKUS_KEYCLOAK_DEVSERVICES_WEB_CLIENT_TIMEOUT

Show more

Duration 

4S

期間フォーマットについて

期間の値を書くには、標準の java.time.Duration フォーマットを使います。 詳細は Duration#parse() Java API documentation を参照してください。

数字で始まる簡略化した書式を使うこともできます:

  • 数値のみの場合は、秒単位の時間を表します。

  • 数値の後に ms が続く場合は、ミリ秒単位の時間を表します。

その他の場合は、簡略化されたフォーマットが解析のために java.time.Duration フォーマットに変換されます:

  • 数値の後に hms が続く場合は、その前に PT が付けられます。

  • 数値の後に d が続く場合は、その前に P が付けられます。

MemorySizeフォーマットについて

A size configuration option recognizes strings in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?.

If no suffix is given, assume bytes.

関連コンテンツ