Auth0 OpenID Connect プロバイダーを使用した Quarkus Web アプリケーションの保護

作業を始める前に、次のドキュメントを確認してください。

Auth0 ダッシュボードに移動し、通常の Web アプリケーションを作成します。 例えば、QuarkusAuth0 という Auth0 アプリケーションを作成します。

Auth0 アプリケーションは、クライアント ID、シークレット、HTTPS ベースのドメインを使用して作成されます。 次の手順で Quarkus 設定を完了するために必要となるため、これらのプロパティーをメモしておいてください。

次に、そのまま Auth0 ダッシュボードでアプリケーションにユーザーを追加します。

これで Auth0 アプリケーションの作成と設定が完了しました。次は、Quarkus エンドポイントの作成と設定を行います。 その後、Auth0 アプリケーションの設定と更新を行います。

次の Maven コマンドを使用して、Quarkus OIDC エクステンションを使用して保護できる Quarkus REST (旧称 RESTEasy Reactive) アプリケーションを作成します。

Windowsユーザーの場合:

アプリケーションワークスペースを作成し、お気に入りの IDE にインポートします。 ここでは、認証されたユーザーのみアクセス可能な Jakarta REST エンドポイントを追加します。

前の手順で作成した Auth0 アプリケーションのプロパティーを使用して、Quarkus の application.properties ファイルで OIDC を設定します。

この手順を完了すると、Auth0 アプリケーションのドメイン、クライアント ID、シークレットを使用するように Quarkus が設定されます。 quarkus.oidc.application-type=web-app プロパティーを設定することで、OIDC 認証コードフローを使用するように Quarkus に指示が出されますが、他の方法を使用することもできます。これについてはチュートリアルの後半で説明します。

エンドポイントアドレスは http://localhost:8080/hello になります。これは、Auth0 アプリケーションで許可されたコールバック URL として登録する必要があります。

この手順を完了すると、ブラウザーから Quarkus http://localhost:8080/hello エンドポイントにアクセスすると、認証が完了した後に Auth0 によって同じアドレスにリダイレクトされます。

これで、エンドポイントのテストを開始する準備が完了しました。

Quarkus を開発モードで起動します。

ブラウザーを開き、http://localhost:8080/hello にアクセスします。

Auth0 にリダイレクトされ、ログインするように求められます。

次に、QuarkusAuth0 アプリケーションによるアカウントへのアクセスを認可します。

最後に、Quarkus エンドポイントにリダイレクトされ、次のレスポンスが返されます。 Hello, auth0|60e5a305e8da5a006aef5471

Quarkus は優れた Dev UI エクスペリエンスを提供します。 具体的には、Quarkus は、Keycloak コンテナーを使用して OIDC エンドポイントを開発およびテストするための組込サポートを提供します。 Quarkus の quarkus.oidc.auth-server-url 設定プロパティーに OIDC プロバイダーのアドレスが指定されていない場合、DevService for Keycloak が自動的に起動され、使用されます。

プロバイダーがすでに設定されている場合は、引き続き Quarkus OIDC Dev UI を使用できます。 設定を更新するには、次の手順を実行します。

まず、次のように Quarkus アプリケーションタイプを web-app から hybrid に変更します。

通常、Quarkus は ベアラー トークン認証をサポートするために quarkus.oidc.application-type=service で設定する必要がありますが、hybrid アプリケーションタイプもサポートしているため、認可コードとベアラートークンの両方のフローを同時にサポートできます。

また、OIDC Dev UI へのコールバックを許可するように Auth0 アプリケーションを設定する必要もあります。 次の URL 形式を使用します。

http://localhost:8080/q/dev-ui/io.quarkus.quarkus-oidc/${provider-name}-provider

これで Auth0 で OIDC Dev UI を使用する準備が完了しました。

ブラウザーセッションで http://localhost:8080/q/dev/ を開きます。以下のように、Auth0 プロバイダー SPA にリンクする OpenId Connect カードが表示されます：

Auth0 provider、Login into Single Page Application の順にクリックします。

ログインのために Auth0 にリダイレクトされます。 その後、次のように、OIDC Dev UI ダッシュボードにリダイレクトされます。

ここでは、エンコードおよびデコードされた ID トークンとアクセストークンを確認し、それをクリップボードにコピーしたり、サービスエンドポイントのテストに使用したりできます。後でエンドポイントをテストしますが、ここではまず ID トークンを確認します。

ご覧のとおりユーザー名を表すクレームはありませんが、sub (subject) クレームを確認すると、その値が、ブラウザーから直接 Quarkus エンドポイントにアクセスした際にレスポンスとして取得した値 (auth0|60e5a305e8da5a006aef5471) と一致することがわかります。

これを修正するには、認証プロセス中に標準の OIDC profile スコープを要求するように Quarkus を設定します。これにより、ID トークンにさらに多くの情報が含まれるようになります。

http://localhost:8080/q/dev/ に戻り、Auth0 へのログインプロセスを繰り返して ID トークンを再度確認すると、name クレームを含む ID トークンが表示されるはずです。

ブラウザーから Quarkus エンドポイントに直接アクセスすると、名前が返されるはずです。しかし、ブラウザーの Cookie キャッシュをクリアして http://localhost:8080/hello にアクセスしても、再度 Hello, auth0|60e5a305e8da5a006aef5471 が返されます。何が間違っているのでしょうか?

答えは、org.eclipse.microprofile.jwt.JsonWebToken#getName() 実装の詳細にあります。 MicroProfile MP JWT RBAC の仕様 によると、この実装は MP JWT 固有の upn クレームをチェックし、次に preferred_username を試行し、最後に sub を試行します。これが、ID トークンに name クレームが含まれていても、レスポンスとして Hello, auth0|60e5a305e8da5a006aef5471 が返される理由です。これは、エンドポイント hello() メソッドの実装を、特定のクレーム値を返すように変更することで、簡単に修正できます。

次にブラウザーのキャッシュをクリアして http://localhost:8080/hello にアクセスすると、ユーザー名が返されます。

これで、ユーザーは Auth0 を使用して Quarkus にサインインできるようになりました。次は、ユーザー主導のログアウトのサポートが必要になるのではないでしょうか。Quarkus は、 RP-initiatedおよび他の標準的な OIDC ログアウトメカニズム、およびローカルセッションログアウト をサポートしています。

現在、Auth0 は標準の OIDC RP-initiated Logoutをサポートしておらず、検出可能なメタデータにセッション終了エンドポイント URL を提供していませんが、標準のものとほぼ同じように動作する独自のログアウトメカニズムを提供しています。

Quarkus OIDC を使用するとこれを簡単にサポートできます。Auth0 のセッション終了エンドポイント URL を設定し、Quarkus で、client-id クエリーパラメーターとログアウト後の URL の両方を、returnTo クエリーパラメーターとしてAuth0 への RRP-initated logoutリダイレクトリクエストに含める必要があります。

ここでは、Auth0 セッション終了エンドポイント URL をカスタマイズし、Quarkus に対して、http://localhost:8080/logout リクエストが現在認証されているユーザーのログアウトをトリガーする必要があることを示しました。/logout パスについては、それが virtual であり、JAX-RS エンドポイントのどのメソッドでもサポートされていないことに留意する必要があります。これが理由で、Quarkus OIDC が /logout リクエストに反応するためには、設定でこのパスに直接 authenticated HTTP セキュリティーポリシー をアタッチする必要があります。

また、ログアウトしたユーザーをパブリック /hello/post-logout リソースに返すように Quarkus を設定しました。このパスは、Auth0 固有の returnTo クエリーパラメーターとしてログアウトリクエストに含まれています。Quarkus アプリケーションの client-id もログアウト URL に含まれています。

ログアウト後のリダイレクトを受け入れるようにエンドポイントを更新します。

パブリック /hello/post-logout リソースメソッドが追加されたことに注意してください。

ログアウトをテストする前に、ユーザーがログアウトした後の Quarkus へのリダイレクトを許可するように、Auth0 アプリケーションが設定されていることを確認します。

ここで、ブラウザーの Cookie キャッシュをクリアし、http://localhost:8080/hello にアクセスし、Auth0 で Quarkus にログインしてユーザー名を取得し、http://localhost:8080/logout に移動します。ブラウザーには、You were logged out というメッセージが表示されます。

次に、http://localhost:8080/q/dev/ に移動し、Dev UI SPA から Auth0 にログインします。Logged in as Sergey Beryozkin というテキストの横に、ログアウトを表す記号が表示され、OIDC Dev UI からもログアウトが可能になったことがわかります。

OIDC DevUI からのログアウトが機能するためには、Auth0 アプリケーションの許可されたログアウトコールバックのリストを更新して、OIDC DevUI エンドポイントを含める必要があります。

次に、OIDC Dev UI から直接ログアウトし、新しいユーザーとしてログインします。必要に応じて、登録済みの Auth0 アプリケーションにさらにユーザーを追加します。

Auth0 を使用して認証されたユーザーが Quarkus エンドポイントにアクセスできることを確認しました。

次の手順では、ロールベースのアクセス制御 (RBAC) を導入して、admin など特定のロールを持つユーザーのみがエンドポイントにアクセスできるようにします。

以下の 権限ベースのアクセス制御 セクションも参照してください。

デフォルトで、Auth0 トークンにはロールを含むクレームは含まれていないため、まず、トークンにロールを追加するカスタムアクションを使用して、Auth0 アプリケーションの Login フローをカスタマイズする必要があります。Auth0 ダッシュボードで Actions/Flows/Login を選択し、Add Action/Build Custom を選択し、AddRoleClaim という名前を付けます。

そこに次のアクションスクリプトを追加します。

カスタム Auth0 クレームは namespace で修飾される必要があるため、ロールを含むクレームの名前は https://quarkus-security.com/roles になります。前のセクションで分析した ID トークンのコンテンツを確認すると、このクレームがどのように表現されているかがわかります。以下はその例です。

Auth0 ログインフロー図は次のようになります。

Auth0 アプリケーションに登録されているユーザーに、admin などのロールを追加する必要があります。

admin ロールを作成します。

それを登録済みユーザーに追加します。

次に、Quarkus エンドポイントを更新して、admin ロールを持つユーザーのみがエンドポイントにアクセスできるようにします。

http://localhost:8080/hello を開き、Auth0 に対して認証すると 403 が発生します。ここでは、Quarkus OIDC が Auth0 トークンのどのクレームがロール情報を表しているか認識していないため、403 が発生します。デフォルトでは groups クレームがチェックされますが、ここでは Auth0 トークンに "https://quarkus-security.com/roles" クレームがあることが期待されます。

RBAC を適用するためにどのクレームをチェックする必要があるかを Quarkus OIDC に指示して修正します。

ブラウザーの Cookie キャッシュをクリアし、再度 http://localhost:8080/hello にアクセスし、Auth0 に対して認証して期待されるユーザー名を取得します。

これまで、OIDC 認可コードフローを使用して Quarkus エンドポイントのみをテストしてきました。このフローでは、ブラウザーを使用して Quarkus エンドポイントにアクセスし、Quarkus 自体が認可コードフローを管理します。ユーザーは Auth0 にリダイレクトされてログインし、Quarkus に再度リダイレクトされます。その後 Quarkus が ID トークン、アクセストークン、およびリフレッシュトークンのコードを交換してフローを完了し、ユーザー認証の成功を表す ID トークンを処理します。この時点でアクセストークンは使用されません。前述のとおり、Quarkus が認可コードフローでアクセストークンを使用するのは、認証済の現行ユーザーに代わってダウンストリームサービスにアクセスする場合に限られます。

しかし、開発した Quarkus エンドポイントも ベアラー アクセストークンを受け入れる必要があると想像してみてください。このエンドポイントにそれを伝播している他の Quarkus エンドポイントかもしれませんし、アクセストークンを使用して Quarkus エンドポイントにアクセスする SPA かもしれません。その場合、すでに ID トークンの分析に使用した Quarkus OIDC DevUI SPA は、SPA が使用できるアクセストークンを使用して Quarkus エンドポイントをテストするのに最適です。

再度 http://localhost:8080/q/dev-ui にアクセスし、OpenId Connect カードを選択して Auth0 にログインし、アクセストークンの内容を確認します。

このアクセストークンは、JWS (署名済み) フォーマットではなく JWE (暗号化済み) フォーマットであるため、前述の ID トークンとは異なり Quarkus が直接検証することはできません。デコードされたトークンヘッダーを見ると、Auth0 のみが知る秘密鍵で直接暗号化されているため、Quakus はその内容を復号化できないことがわかります。このアクセストークンは Quarkus から見ると 不透明 であり、Quarkus は Auth0 の公開非対称検証キーを使用してこれを検証することはできません。

確認するには、Test Service 領域の Service Address として /hello を入力して With Access Token を押すと、HTTP 401 ステータスが表示されます。

Quarkus がこのようなアクセストークンを受け入れるには、2 つのオプションのいずれかを使用できなければなりません。 最初のオプションは、プロバイダーのイントロスペクションエンドポイントを使用して、不透明トークンをリモートでイントロスペクトします。通常、トークンイントロスペクションは OAuth2 レベルでサポートされ、OIDC は OAuth2 上に構築されているため、Keycloak などの一部の OIDC プロバイダーもトークンイントロスペクションをサポートします。ただし、Auth0 はトークンイントロスペクションをサポートしません。確認するには、公開されている Auth0 メタデータを確認し、設定済みの Auth0 プロバイダーのアドレスに /.well-known/openid-configuration を追加し、その結果として得られる URL https://dev-3ve0cgn7.us.auth0.com/.well-known/openid-configuration を開きます。これにより、Auth0 にイントロスペクションエンドポイントがないことがわかります。

この場合は、別のオプションを使用できます。つまり、アクセストークンを使用して Auth0 から UserInfo を取得し、間接的にアクセストークンを検証するというもう 1 つのオプションを使用して、不透明な Auth0 トークンを受け入れ、検証できます。OIDC プロバイダーは UserInfo を発行する前にアクセストークンを検証する必要があり、Auth0 には UserInfo エンドポイントがあるため、このオプションが機能します。

ここで、アクセストークンを使用して UserInfo を取得することでアクセストークンの検証行うことをリクエストするように、Quarkus を設定してみましょう。

ID token ではなく UserInfo を期待するように、エンドポイントコードを更新します。

このコードは、認可コードフローとベアラーアクセストークンフローの両方で機能するようになります。

アクセストークンを確認した OIDC Dev UI に移動し、Test Service 領域の Service Address として /hello を入力し、With Access Token を押すと 200 が返されます。

実際に動作することを確認するには、@RolesAllowed("user") でのみ user ロールを許可するようにテストエンドポイントを更新します。その後、OIDC Dev UI からエンドポイントに再度アクセスすると、HTTP 403 エラーが発生します。コードを @RolesAllowed ("admin") に戻すと、HTTP 200 ステータスが再び表示されます。

不透明アクセストークンを間接的に検証する場合、それを使用して UserInfo をリクエストすると、Quarkus はロール情報のソースとして UserInfo を使用します (存在する場合)。その結果、Auth0 は UserInfo レスポンスに以前に作成されたカスタムロールクレームも含めます。

OIDC 認可コードフローを使用し、ID トークンと UserInfo の両方を使用してユーザー情報にアクセスできるようになりました。一般的な次のタスクは、現在の Auth0 アクセストークンを伝播して、現行の認証済みユーザー代わってダウンストリームサービスにアクセスすることです。

実際、注入された UserInfo を示す最後のサンプルコードは、具体的なアクセストークンを伝播した例です。この場合、Quarkus は Auth0 アクセストークンを Auth0 UserInfo エンドポイントに伝播して UserInfo を取得します。Quarkus は、ユーザーが何もしなくてもこれを実行します。

しかし、アクセストークンを一部のカスタムサービスに伝播させる場合はどうでしょうか。Quarkus では、認可コードフローとベアラートークンフローの両方で非常に簡単にこれを実現できます。ベアラートークンアクセスを必要とするサービスを呼び出すための REST クライアントインターフェイスを作成し、それにアノテーション @AccessToken を付けるだけで、Auth0 ベアラーアクセストークンとしてフロントエンドエンドポイントに到着するアクセストークン、または Auth0 認可コードフローの完了後に Quarkus が取得したアクセストークンが、ターゲットマイクロサービスに伝播されます。これ以上簡単にはならないぐらい簡単です。

For examples of propagating access tokens, see the following sections in this tutorial. For more information about token propagation, see OIDC token propagation.

すでに OIDC DevUI SPA を使用して Auth0 にログインし、アクセストークンを使用して Quarkus エンドポイントをテストし、その過程でエンドポイントコードを更新しています。

しかし、テストの実行も重要です。ここでは、Quarkus 継続的テスト 機能を使用して、このチュートリアルを実施する中で開発したエンドポイントと設定をテストする方法を説明します。

次のテストコードから始めます。

アプリケーションを開発モードで起動すると、CLI ウィンドウに次のように表示されます。

r を押すと、このテストが 403 で失敗していることがわかります。テストはエンドポイントにトークンを送信しないため、これは想定された結果です。

Before fixing the test, let’s review the options available for testing Quarkus endpoints secured by OIDC. These options might vary, depending on which flow your application supports and how you prefer to test. Endpoints which use OIDC authorization code flow can be tested using one of these options and endpoints which use Bearer token authentication can be tested using one of these options.

このように、Auth0 で保護されたエンドポイントは、Wiremock または @TestSecurity アノテーションを使用してテストできます。このようなテストを自分で書いてみて、問題が発生した場合はご連絡ください。

ただしこのチュートリアルでは、最近追加された OidcTestClient を使用して、ライブ Auth0 開発テナントを使用するエンドポイントのテストをサポートします。

関連する設定フラグメントを次に示します。

実稼働環境では、%prod. および %test. 修飾子を使用して本番レベルとテストレベルの設定を区別します。ここでは、実際のアプリケーションで上記の設定が %test. から始まり、この設定に %prod. で修飾された Auth0 実稼働テナント設定が含まれると仮定します。

OidcTestClient を使用してこのような設定をテストするには、OAuth2 password または client_credentials グラントのいずれかを使用して、Auth0 開発テナントからトークンを取得する必要があります。ここでは password グラントを使用します。Auth0 ダッシュボードに登録されているアプリケーションが password グラントを許可していることを確認してください。

OidcTestClient should be used to test applications accepting bearer tokens which will work for the endpoint developed in this tutorial as it supports both authorization code flow and bearer token authentication. You would need to use OIDC WireMock or HtmlUnit directly against the Auth0 dev tenant if only the authorization code flow was supported - in the latter case HtmlUnit test code would have to be aligned with how Auth0 challenges users to enter their credentials. If you like, you can copy the HtmlUnit test fragment from the documentation and experiment with it.

ここでは OidcTestClient を使用して、現時点で失敗しているテストを修正します。

まず、次の依存関係を追加する必要があります。

これは、アクセストークンの取得テストに使用できるユーティリティークラス io.quarkus.test.oidc.client.OidcTestClient を提供します (この依存関係は OIDC WireMock サポートも提供しますので、必要に応じてドキュメントでテストに使用する方法を確認してください)。

次に、テストコードを以下のように更新します。

OidcTestClient は、Auth0 トークンのエンドポイントのアドレス、クライアント id、およびシークレットを検出します。

もう一度 r を押すと、テストが合格します。

ちなみに、必要に応じて DevUI から直接、連続モードでテストを実行することもできます。

Auth0 で保護された Quarkus エンドポイントを開発モードで開発およびテストしました。 次のステップでは、アプリケーションを本番モードで実行します。 JVM モードとネイティブモードを選択します。

このチュートリアルで説明された手順は、チュートリアルで説明されたとおりに動作するはずです。すでに認証を完了している場合は、更新後の Quarkus エンドポイントにアクセスする際にブラウザーの Cookie をクリアする必要があることもあります。開発モードで Quarkus アプリケーションを手動で再起動する必要がある可能性もありますが、これhら想定されていません。このチュートリアルを完了するのにサポートが必要な場合は、Quarkus チームにお問い合わせください。

このチュートリアルでは、同じエンドポイントコードでサポートされている認可コードフローとベアラートークン認証フローを使用して、Quarkus エンドポイントを quarkus-oidc エクステンションと Auth0 で保護する方法を実演しました。 コードを 1 行も書くことなく、カスタム Auth0 ログアウトフローのサポートを追加し、namespace で修飾されたカスタム Auth0 クレームを使用してロールベースのアクセス制御を有効にしました。 マイクロサービス REST クライアントに @AccessToken アノテーションを追加することで、フロントエンドエンドポイントからマイクロサービスエンドポイントにトークンを伝播しました。 マイクロサービスエンドポイントは、@PermissionsAllowed アノテーションを使用して権限ベースのアクセス制御を有効にしました。 Quarkus 開発モードを使用して、エンドポイントを再起動せずにコードと設定を更新し、OIDC Dev UI を使用して Auth0 トークンを視覚化およびテストしました。 Quarkus の継続的テスト機能を使用して、OIDC Dev UI テストをライブ Auth0 開発テナントに対する統合テストで補完しました。 最後に、アプリケーションを JVM モードとネイティブモードで実行しました。

どうぞお楽しみください。