OpenID Connect を使用した Microsoft Entra ID による Quarkus アプリケーションの保護

[アーティクル]
10/07/2024

この記事では、OpenID Connect (OIDC) を使用して、Microsoft Entra ID で Red Hat Quarkus アプリケーションをセキュリティで保護する方法について説明します。

この記事では、次のことについて説明します。

Microsoft Entra ID を使用して、OpenID Connect プロバイダーを設定します。
OpenID Connect を使用して、Quarkus アプリを保護します。
Quarkus アプリを実行してテストします。

前提条件

Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
少なくともクラウドアプリケーション管理者 Microsoft Entra ロールを持つ Azure ID。詳細については、「Microsoft Entraロールの割り当て一覧表示」および「Microsoft Entra 組み込みロール」を参照してください。
Microsoft Entra テナント。既存のテナントがない場合は、「Quickstart: テナントの設定」を参照してください。
Unix のようなオペレーティングシステム (Ubuntu、macOS、Linux 用 Windows サブシステムなど) がインストールされているローカルマシン。
Git.
Java SE 実装バージョン 21 以降 (OpenJDK の Microsoft ビルドなど) をインストールします。
Maven バージョン 3.9.3 以降。

Microsoft Entra ID を使用して、OpenID Connect プロバイダーを設定する

このセクションでは、Microsoft Entra ID で OpenID Connect プロバイダーを設定して、Quarkus アプリで使用します。後のセクションでは、OpenID Connect を使用して Microsoft Entra テナントのユーザーを認証および承認することで、Quarkus アプリを構成します。

Microsoft Entra テナントにユーザーを作成する

まず、「ユーザーを作成、招待、削除する方法」の手順に従って、Microsoft Entra テナントに 2 人のユーザーを作成します。必要なのは、「新しいユーザーの作成」セクションだけです。この記事を読み進める際には、以下の手順に従い、Microsoft Entra テナントにユーザーを作成した後でこの記事に戻ってください。

アプリで「管理者」として機能するユーザーを作成するには、次の手順に従います。

[新しいユーザーの作成]セクションの [基本] タブに移動したら、次の手順を実行します。
1. [ユーザープリンシパル名] に「管理者」と入力します。後でアプリにサインインするときに使用できるように、値を保存します。
2. [メールニックネーム] で、[Derive from user principal name] (ユーザープリンシパル名から派生する) を選択します
3. [表示名] に「管理者」と入力します。
4. [パスワード] で、[パスワードの自動生成] を選択します。後でアプリにサインインするときに使用するパスワード値をコピーして保存します。
5. [アカウントが有効] を選択します。
6. [確認と作成]>[作成] の順に選択します。ユーザーが作成されるまで待ちます。
7. 少し待ってから、更新] を選択します。新しいユーザーがリストに表示されます。

アプリ内で「ユーザー」として機能するユーザーを作成するには、これらの手順を繰り返しますが、次の値を使用します。

[ユーザープリンシパル名] に、「ユーザー」と入力します。
[表示名] に「ユーザー」と入力します。

Microsoft Entra ID でアプリケーションの登録

次に、以下の手順に従ってアプリケーションを登録するには、「クイックスタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。この記事を読みながら次の指示に従い、アプリケーションを登録して構成した後でこの記事に戻ってください。

「アプリケーションを登録する」セクションにアクセスしたら、次の手順を実行します。
1. [サポートされているアカウントの種類] で、 [Accounts in this organizational directory only (Default Directory only - Single tenant)] (この組織ディレクトリのアカウントのみ (既定のディレクトリのみ - シングルテナント)) を選択します。
2. 登録が完了したら、アプリケーション (クライアント) ID と ディレクトリ (テナント) ID 値を保存して、後でアプリ構成で使用します。
[リダイレクト URI の追加] セクションにアクセスしたら、今の時点では手順をスキップします。この記事では、後でサンプルアプリをローカルで実行してテストするときに、リダイレクト URI を追加します。
[資格情報の追加] セクションに到達したら、 [クライアントシークレットの追加] タブを選択します。
クライアントシークレットを追加するときは、後でアプリ構成で使用する [クライアントシークレット] 値を書き留めます。

アプリケーションにアプリロールを追加する

次に、「アプリケーションにアプリロールを追加し、トークンで受け取る」の手順に従って、アプリケーションにアプリロールを追加します。必要なのは、「アプリケーションのロール宣言」セクションと「ユーザーとグループを Microsoft Entra ロールに割り当てる」セクションだけです。この記事を読み進める際には次の指示に従い、アプリケーションのロール宣言が完了したらこの記事に戻ってください。

「アプリケーションのロールを宣言する」セクションに到達したら、[アプリロール] UI を使用して、管理者と通常のユーザーのロールを作成します。
1. 次の値を使用して管理者ユーザーロールを作成します。
  - [表示名] に「管理者」と入力します。
  - [許可されたメンバーの種類] で [ユーザー/グループ] を選択します。
  - [値] には、「admin」と入力します。
  - [説明] に「管理者」と入力します。
  - [Do you want to enable this app role?] (このアプリのロールを有効にしますか?) を選択します。
2. 適用を選択します。ロールが作成されるまで待ちます。
3. 同じ手順で、次の値を使用して通常のユーザーロールを作成します。
  - [表示名] に「ユーザー」と入力します。
  - [値] には、「管理者」と入力します。
  - [説明] には、「ユーザー」と入力します。
「Microsoft Entra ロールへのユーザーとグループの割り当て」セクションに到達したら、次の手順を使用します。
1. [Add user/group](ユーザーまたはグループの追加) を選択します。
2. [割り当ての追加] ウィンドウの [ユーザー]で、ユーザー [管理者] を選択し、[ロールの選択] を選択して、ロール [管理者] を選択します。次に、[割り当て] を選択します。アプリケーションの割り当てが成功するまで待ちます。テーブルを横にスクロールして、[割り当てられたロール] 列を表示する必要がある場合があります。
3. 前の手順を繰り返して、ユーザー ロールをユーザー [ユーザー] に割り当てます。
4. [更新] を選択すると、[ユーザーとグループ] ペインに割り当てられているユーザーとロールが表示されます。
  
  ビューを画像のように見えるようにするには、列ヘッダーの幅を調整する必要がある場合があります。

「アプリケーションにアプリロールを追加し、トークンで受け取る」の手順は実行しないでください。

OpenID Connect を使用して、Quarkus アプリを保護する

このセクションでは、OpenID Connect を使用して、Microsoft Entra テナント内のユーザーを認証および承認する Quarkus アプリを保護します。また、ロールベースのアクセス制御 (RBAC) を使用して、アプリの特定の部分へのアクセス権をユーザーに付与する方法についても説明します。

このクイックスタートのサンプル Quarkus アプリは、[quarkus-azure] リポジトリの GitHub にあり、[entra-id-quarkus] ディレクトリにあります。

認証と承認を有効にしてアプリのセキュリティを確保する

アプリには、次のコード例に示すように、WelcomePage.java で定義されたウェルカムページリソースがあります。このページには、認証されていないユーザーがアクセスできます。ウェルカムページのルートパスは、/ にあります。

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

ウェルカムページから、ユーザーはアプリにサインインしてプロファイルページにアクセスできます。ウェルカムページには、ユーザーまたは管理者としてサインインするためのリンクがあります。リンクはそれぞれ /profile/user と /profile/admin にあります。ウェルカムページ UI は、welcome.qute.html で定義され、次の例に示されています。

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

/profile/user と /profile/adminの両方のリンクは、次のコード例に示すように、ProfilePage.java で定義されているプロファイルページリソースを指します。このページには、jakarta.annotation.security.RolesAllowed パッケージの @RolesAllowed("**") 注釈を使用して、認証されたユーザーのみがアクセスできます。 @RolesAllowed("**")注釈は、認証されたユーザーのみが /profile パスにアクセスできることを指定します。

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

プロファイルページリソースは、@RolesAllowed 注釈を使用して RBAC を有効にします。 @RolesAllowed 注釈の引数では、admin ロールを持つユーザーのみが /profile/admin パスにアクセスでき、user または admin ロールを持つユーザーのみが /profile/user パスにアクセスできることを指定します。

/profile/admin エンドポイントと /profile/user エンドポイントの両方がプロファイルページを返します。プロファイルページ UI は、次の例に示すように、profile.qute.html で定義されます。このページには、ユーザーの名前、ロール、およびスコープが表示されます。プロファイルページには、/logout にサインアウトリンクもあり、ユーザーを OIDC プロバイダーにリダイレクトしてサインアウトします。プロファイルページは、Qute テンプレートエンジンを使用して記述されます。ページでの {} 式の使用に注意してください。これらの式では、data() メソッドを使用して TemplateInstance に渡される値を使用します。 Qute の詳細については、「Qute テンプレートエンジン」を参照してください。

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

サインアウト後、ユーザーはウェルカムページにリダイレクトされ、再度サインインできるようになります。

Quarkus アプリを実行してテストする

このセクションでは、Quarkus アプリを実行してテストし、OpenID Connect プロバイダーとして Microsoft Entra ID を使用してどのように動作するかを確認します。

アプリケーション登録にリダイレクト URI を追加する

アプリをローカルで正常に実行してテストするには、アプリ登録にリダイレクト URI を追加する必要があります。「クイックスタート: マイクロソフト ID プラットフォームを使用してアプリケーションを登録する」の「リダイレクト URI を追加する」セクションの手順を実行して、次の値をしっ要します。

[プラットフォームの構成] で [Web] を選びます。
[リダイレクト URI] に「http://localhost:8080」を入力します。

サンプルを準備する

サンプル Quarkus アプリを準備するには、次の手順に従います。

次のコマンドを使用して、GitHub からサンプル Quarkus アプリをクローンし、entra-id-quarkus ディレクトリに移動します。
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
HEAD がデタッチされた状態であることを示すメッセージが表示された場合、このメッセージは無視しても問題ありません。この記事ではコミットを必要としないため、HEAD がデタッチされた状態が適切です。
次のコマンドを使用して、前に書き留めた値で次の環境変数を定義します。
```
export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
```
これらの環境変数は、Quarkus の OpenID Connect の組み込みサポートの値を提供します。 application.properties の対応するプロパティを次の例に示します。
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
application.properties でプロパティの値が空白の場合、Quarkus はプロパティ名を環境変数に変換し、環境から値を読み取ります。命名変換の詳細については、「MicroProfile Config の仕様」を参照してください。

Quarkus アプリを実行する

Quarkus アプリはさまざまなモードで実行できます。以下のいずれかの方法を選択して、Quarkus アプリを実行します。 Quarkus が Microsoft Entra ID に接続できるようにするには、前のセクションで示した環境変数を定義したシェルでコマンドを必ず実行してください。

Quarkus アプリを開発モードで実行します。
```
mvn quarkus:dev
```

Quarkus アプリを JVM モードで実行します。

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

Quarkus アプリをネイティブモードで実行します。

mvn install -Dnative -Dquarkus.native.container-build
./target/quarkus-ad-1.0.0-SNAPSHOT-runner

さまざまなモードを試す場合は、Ctrl+C を使用して Quarkus アプリを停止し、別のモードで Quarkus アプリを実行します。

Quarkus アプリをテストする

Quarkus アプリが実行されたら、プライベートタブで Web ブラウザーを開き、http://localhost:8080 に移動します。ウェルカムページが表示され、ユーザーまたは管理者としてサインインするためのリンクが表示されます。プライベートタブを使用すると、通常のブラウザーで実行されている既存の Microsoft Entra ID アクティビティが汚染されることがなくなります。

2 人のユーザーの資格情報を収集する

この記事では、Microsoft Entra ID はサインイン用のユーザー ID として各ユーザーのメールアドレスを使用します。管理者ユーザーと通常ユーザーのメールアドレスを取得するには、次の手順に従います。

クラウドアプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
複数のテナントにアクセスできる場合は、トップメニューの [設定] アイコン ( ) を使用して、[ディレクトリ + サブスクリプション] メニューからアプリケーションを登録するテナントに切り替えます。
[ID] > [ユーザー] > [すべてのユーザー] を参照します。
一覧で管理者ユーザーを見つけて選択します。
[ユーザープリンシパル名] フィールドを見つけます。
フィールドの値の横にあるコピーアイコンを使用して、ユーザーのメールアドレスをクリップボードに保存します。後で使用するために値を保存します。
通常のユーザーのメールアドレスを取得するには、同じ手順に従います。

管理者ユーザーと、ユーザーの作成時に設定した通常のユーザーのパスワードを使用します。

アプリの機能を実行する

機能を実行するには、次の手順に従います。

[ユーザーとしてサインイン] リンクを選択します。先ほど作成した通常のユーザーとしてサインインします。サインインすると、Microsoft Entra ID によってプロファイルページにリダイレクトされ、名前、ロール、スコープが表示されます。
初めてサインインする場合は、パスワードを更新するように求められます。手順に従ってパスワードを更新します。
メッセージが表示された場合は、組織で追加のセキュリティ情報が必要です。指示に従って Microsoft Authenticator アプリをダウンロードしてセットアップします。[後で質問する] を選択してテストを続行できます。
[要求されているアクセス許可] を求められた場合は、アプリによって要求されたアクセス許可を確認します。 [同意する] を選択してテストを続行します。
[サインアウト] を選択して、Quarkus アプリからサインアウトします。 Microsoft Entra ID がサインアウトを実行します。サインアウト後、Microsoft Entra ID はウェルカムページにリダイレクトします。
[管理者としてサインイン] リンクを選択します。 Microsoft Entra IDは、サインインページにリダイレクトします。先ほど作成した管理者ユーザーとしてサインインします。サインインすると、Microsoft Entra ID によって、別のロール admin を持つ同様のプロファイルページにリダイレクトされます。
もう一度サインアウトし、前に作成した通常のユーザーで管理者としてサインインを試みます。通常のユーザーには admin ロールがないため、エラーメッセージが表示されます。

リソースをクリーンアップする

この記事では、アプリを Azure にデプロイする方法については説明しません。 Microsoft Entra ID リソースはありますが、アプリ用にクリーンアップする Azure リソースはありません。アプリを Azure にデプロイするには、次のセクションで参照されているガイダンスに従ってください。

このサンプルアプリのリソースの使用が完了したら、次の手順に従って Microsoft Entra ID リソースをクリーンアップします。使用されていない Microsoft Entra ID リソースを削除することは、重要なセキュリティのベストプラクティスです。

「Microsoft ID プラットフォームに登録されているアプリケーションを削除する」手順に従って、作成したアプリの登録を削除します。必要なのは、「組織が作成したアプリケーションの削除」セクションの手順に従うだけです。
アプリの登録を削除すると、エンタープライズアプリケーションも削除されます。エンタープライズアプリケーションの削除の詳細については、「エンタープライズアプリケーションの削除」を参照してください。
「ユーザーを作成、招待、削除する方法」の手順に従って、作成したユーザーを削除します。

次のステップ

このクイックスタートでは、OpenID Connect を使用して Microsoft Entra ID で Quarkus アプリケーションを保護します。詳細については、次のリソースを参照してください。

次の方法で共有

OpenID Connect を使用した Microsoft Entra ID による Quarkus アプリケーションの保護

前提条件

Microsoft Entra ID を使用して、OpenID Connect プロバイダーを設定する

Microsoft Entra テナントにユーザーを作成する

Microsoft Entra ID でアプリケーションの登録

アプリケーションにアプリロールを追加する

OpenID Connect を使用して、Quarkus アプリを保護する

認証と承認を有効にしてアプリのセキュリティを確保する

Quarkus アプリを実行してテストする

アプリケーション登録にリダイレクト URI を追加する

サンプルを準備する

Quarkus アプリを実行する

Quarkus アプリをテストする

2 人のユーザーの資格情報を収集する

アプリの機能を実行する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

次の方法で共有

OpenID Connect を使用した Microsoft Entra ID による Quarkus アプリケーションの保護

前提条件

Microsoft Entra ID を使用して、OpenID Connect プロバイダーを設定する

Microsoft Entra テナントにユーザーを作成する

Microsoft Entra ID でアプリケーションの登録

アプリケーションにアプリ ロールを追加する

OpenID Connect を使用して、Quarkus アプリを保護する

認証と承認を有効にしてアプリのセキュリティを確保する

Quarkus アプリを実行してテストする

アプリケーション登録にリダイレクト URI を追加する

サンプルを準備する

Quarkus アプリを実行する

Quarkus アプリをテストする

2 人のユーザーの資格情報を収集する

アプリの機能を実行する

リソースをクリーンアップする

次のステップ

フィードバック

その他のリソース

アプリケーションにアプリロールを追加する