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

OpenID Connect (OIDC) 認可コードフローを使用して Web アプリケーションを保護

Quarkus OIDC エクステンションによる Quarkus OpenID Connect (OIDC) 認可コードフローメカニズムを使用して、アプリケーションの HTTP エンドポイントを保護し、堅牢な認証と認可を実現する方法をご覧ください。

詳細については、Web アプリケーションを保護するための OIDC コードフローメカニズム を参照してください。

Apple、Facebook、GitHub、Google、Mastodon、Microsoft、Spotify、Twitch、X (旧 Twitter) など、よく知られているソーシャルプロバイダーを Quarkus OIDC で使用する方法については、よく知られている OpenID Connect プロバイダーの設定 を参照してください。Quarkus の認証メカニズム も参照してください。

OIDC ベアラー認証を使用してサービスアプリケーションを保護したい場合は、OIDC ベアラー認証 を参照してください。

前提条件

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

  • 約15分

  • IDE

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

  • Apache Maven 3.9.15

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

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

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

アーキテクチャー

この例では、単一ページでシンプルな Web アプリケーションを構築します。

  • /index.html

このページは保護されており、認証されたユーザーのみがアクセスできます。

ソリューション

次のセクションの指示に従って、アプリケーションを段階的に作成してください。あるいは、完成した例にすぐに進むこともできます。

git clone https://github.com/quarkusio/quarkus-quickstarts.git コマンドを実行して Git リポジトリーをクローンします。あるいは、https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip[アーカイブ] をダウンロードしてください。

ソリューションは security-openid-connect-web-authentication-quickstart ディレクトリー にあります。

1. Maven プロジェクトの作成

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

コマンドラインインタフェース
quarkus create app org.acme:security-openid-connect-web-authentication-quickstart \
    --extension='rest,oidc' \
    --no-code
cd security-openid-connect-web-authentication-quickstart

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

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

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.35.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-openid-connect-web-authentication-quickstart \
    -Dextensions='rest,oidc' \
    -DnoCode
cd security-openid-connect-web-authentication-quickstart

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

Windowsユーザーの場合:

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

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

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

コマンドラインインタフェース
quarkus extension add oidc
Maven
./mvnw quarkus:add-extension -Dextensions='oidc'
Gradle
./gradlew addExtension --extensions='oidc'

これにより、ビルドファイルに以下の依存関係が追加されます。

pom.xml
<dependency>
   <groupId>io.quarkus</groupId>
   <artifactId>quarkus-oidc</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-oidc")

2. アプリケーションの作成

認可コードグラントレスポンスで返されるすべてのトークンが注入された、シンプルな Jakarta REST リソースを作成してみましょう。

package org.acme.security.openid.connect.web.authentication;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;

import org.eclipse.microprofile.jwt.Claims;
import org.eclipse.microprofile.jwt.JsonWebToken;

import io.quarkus.oidc.IdToken;
import io.quarkus.oidc.RefreshToken;

@Path("/tokens")
public class TokenResource {

   /**
    * Injection point for the ID token issued by the OpenID Connect provider
    */
   @Inject
   @IdToken
   JsonWebToken idToken;

   /**
    * Injection point for the access token issued by the OpenID Connect provider
    */
   @Inject
   JsonWebToken accessToken;

   /**
    * Injection point for the refresh token issued by the OpenID Connect provider
    */
   @Inject
   RefreshToken refreshToken;

   /**
    * Returns the tokens available to the application.
    * This endpoint exists only for demonstration purposes.
    * Do not expose these tokens in a real application.
    *
    * @return an HTML page containing the tokens available to the application.
    */
   @GET
   @Produces("text/html")
   public String getTokens() {
       StringBuilder response = new StringBuilder().append("<html>")
               .append("<body>")
               .append("<ul>");


       Object userName = this.idToken.getClaim(Claims.preferred_username);

       if (userName != null) {
           response.append("<li>username: ").append(userName.toString()).append("</li>");
       }

       Object scopes = this.accessToken.getClaim("scope");

       if (scopes != null) {
           response.append("<li>scopes: ").append(scopes.toString()).append("</li>");
       }

       response.append("<li>refresh_token: ").append(refreshToken.getToken() != null).append("</li>");

       return response.append("</ul>").append("</body>").append("</html>").toString();
   }
}

このエンドポイントには ID、アクセス、およびリフレッシュトークンが注入されます。ID トークンからの preferred_username クレーム、アクセストークンからの scope クレーム、およびリフレッシュトークンの可用性ステータスを返します。

トークンを注入する必要があるのは、エンドポイントが ID トークンを使用して現在認証されているユーザーとやり取りする必要がある場合、またはアクセストークンを使用してそのユーザーに代わって下流のサービスにアクセスする必要がある場合のみです。

詳細については、リファレンスガイドの アクセス ID とアクセストークン のセクションを参照してください。

3. アプリケーションの設定

OIDC エクステンションでは、 src/main/resources ディレクトリーにある application.properties ファイルを使用して設定を定義できます。

%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
quarkus.oidc.client-id=frontend
quarkus.oidc.credentials.secret=secret
quarkus.oidc.application-type=web-app
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated

これは、アプリケーションへの認証を有効にする際に最もシンプルな設定です。

quarkus.oidc.client-id プロパティーは OIDC プロバイダーが発行した client_id を参照し、 quarkus.oidc.credentials.secret プロパティーはクライアントシークレットを設定します。

quarkus.oidc.application-type プロパティーを web-app に設定することで、Quarkus に OIDC 認可コードフローを有効にし、ユーザーが認証のために OIDC プロバイダーにリダイレクトされるように指示します。

最後に、保護したいパスについて Quarkus に伝えるために、 quarkus.http.auth.permission.authenticated パーミッションが設定されています。この場合、すべてのパスは、authenticated ユーザーのみがアクセスできるようにするポリシーによって保護されます。詳細については、セキュリティ認可ガイド を参照してください。

quarkus.oidc.credentials.secret でクライアントシークレットを設定しない場合は、quarkus.oidc.token-state-manager.encryption-secret を設定することをお勧めします。

quarkus.oidc.token-state-manager.encryption-secret を使用すると、デフォルトのトークンステートマネージャーがブラウザー Cookie 内のユーザーセッショントークンを暗号化できるようになります。このキーが定義されておらず、quarkus.oidc.credentials.secret フォールバックが設定されていない場合、Quarkus はランダムなキーを使用します。ランダムなキーを使用すると、アプリケーションの再起動時や、アプリケーションの複数のインスタンスがある環境で、既存のログインが無効になります。また、quarkus.oidc.token-state-manager.encryption-required を false に設定することで、暗号化を無効にすることもできます。ただし、シークレットの暗号化は開発環境でのみ無効にしてください。

暗号化のシークレットは 32 文字にすることを推奨します。例えば、quarkus.oidc.token-state-manager.encryption-secret=AyM1SysPpbyDfgZld3umj1qzKObwVMk

4. Keycloak サーバーの起動と設定

Keycloak サーバーを起動するには、Docker を使用し、以下のコマンドを実行します。

docker run --name keycloak -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:26.5.7 start-dev

Keycloak サーバーには localhost:8180 からアクセスできます。

Keycloak 管理コンソールにアクセスするには、admin ユーザーでログインします。ユーザー名とパスワードはいずれも admin です。

新しいレルムを作成するには、レルム設定ファイル をインポートします。詳細については、Keycloak ドキュメントの 新しいレルムの作成と設定 方法を参照してください。

5. 開発モードと JVM モードでアプリケーションを実行

開発モードでアプリケーションを実行するには、次を使用します。

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

開発モードでアプリケーションを試した後、標準の Java アプリケーションとして実行できます。

まず、コンパイルします。

コマンドラインインタフェース
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

次に、実行します。

java -jar target/quarkus-app/quarkus-run.jar

6. ネイティブモードでアプリケーションを実行

この同じデモはネイティブコードにコンパイルできます。変更は必要ありません。

これは、ランタイムテクノロジーが生成されたバイナリーに含まれ、最小限のリソースで実行できるように最適化されているため、本番環境に JVM をインストールする必要がなくなることを意味します。

コンパイルには時間がかかるため、このステップはデフォルトでオフになっています。ネイティブビルドを有効にすれば、再度ビルドできます。

コマンドラインインタフェース
quarkus build --native
Maven
./mvnw install -Dnative
Gradle
./gradlew build -Dquarkus.native.enabled=true

しばらくすると、このバイナリーを直接実行できるようになります。

./target/security-openid-connect-web-authentication-quickstart-runner

7. アプリケーションのテスト

アプリケーションをテストするには、ブラウザを開いて以下の URL にアクセスしてください:

すべてが期待通りに動作すれば、認証のために Keycloak サーバーにリダイレクトされます。

アプリケーションを認証するには、Keycloak のログインページで以下のクレデンシャルを入力してください:

  • ユーザー名: alice

  • パスワード: alice

Login ボタンをクリックすると、アプリケーションにリダイレクトされ、セッションクッキーが作成されます。

このデモのセッションは短時間有効であり、ページを更新するたびに再認証を求められます。 セッションタイムアウトを増やす方法については、Keycloak の セッションタイムアウト ドキュメントを参照してください。 例えば、開発モードで Dev Services for Keycloak を使用している場合、 Keycloak Admin リンクをクリックすることで、dev UI から直接 Keycloak Admin コンソールにアクセスできます:

Dev UI OpenID Connect Card

Dev Services for Keycloak に依存する統合テストの作成に関する詳細は、 Dev Services for Keycloak セクションを参照してください。

まとめ

OIDC 認可コードフローメカニズムを設定して使用し、アプリケーションの HTTP エンドポイントを保護およびテストする方法を学習しました。 このチュートリアルを完了したら、 OIDC ベアラー認証 および 他の認証メカニズム を調べてみてください。

参照

関連コンテンツ

同じエクステンションについて

同じトピックについて

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

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

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.