3.3. 統合に関する考慮事項

シングルページアプリケーション (SPA) を実装する場合は、「OpenID Connect (OIDC) ベアラートークン認証」ガイドの シングルページアプリケーション セクションで提案されている方法を参照してください。

Quarkus Web アプリケーションで Fetch または XMLHttpRequest (XHR) などの SPA および JavaScript API を使用する場合は、Quarkus からのリダイレクト後にユーザーが認証される認証エンドポイントに対して、OIDC プロバイダーが Cross-Origin Resource Sharing (CORS) をサポートしていない可能性があることに注意してください。Quarkus アプリケーションと OIDC プロバイダーが異なる HTTP ドメイン、ポート、またはその両方でホストされている場合は、認証に失敗します。

このような場合は、quarkus.oidc.authentication.java-script-auto-redirect プロパティーを false に設定します。これにより、Quarkus は 499 ステータスコードと OIDC 値を含む WWW-Authenticate ヘッダーを返すように指示されます。

quarkus.oidc.authentication.java-script-auto-redirect プロパティーが false に設定されている場合に 499 ステータスコードが返されるようにするには、ブラウザースクリプトで現在のリクエストを JavaScript リクエストとして識別するヘッダーを設定する必要があります。

スクリプトエンジンがエンジン固有のリクエストヘッダー自体を設定する場合は、カスタム quarkus.oidc.JavaScriptRequestChecker Bean を登録できます。これにより、現在のリクエストが JavaScript リクエストであるかどうかが Quarkus に通知されます。たとえば、JavaScript エンジンが HX-Request: true などのヘッダーを設定する場合は、次のようにチェックできます。

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.oidc.JavaScriptRequestChecker;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomJavaScriptRequestChecker implements JavaScriptRequestChecker {

    @Override
    public boolean isJavaScriptRequest(RoutingContext context) {
        return "true".equals(context.request().getHeader("HX-Request"));
    }
}

ステータスコード 499 の場合は、最後にリクエストされたページを再読み込みします。

それ以外の場合は、ブラウザースクリプトを更新して、X-Requested-With ヘッダーに JavaScript 値を設定し、ステータスコード 499 の場合は最後にリクエストされたページを再読み込みする必要もあります。

以下に例を示します。

Future<void> callQuarkusService() async {
    Map<String, String> headers = Map.fromEntries([MapEntry("X-Requested-With", "JavaScript")]);

    await http
        .get("https://localhost:443/serviceCall")
        .then((response) {
            if (response.statusCode == 499) {
                window.location.assign("https://localhost.com:443/serviceCall");
            }
         });
  }

別のドメインで実行されているシングルページアプリケーションからこのアプリケーションを使用する予定の場合は、Cross-Origin Resource Sharing (CORS) を設定する必要があります。詳細は、"Cross-origin resource sharing" の CORS filter セクションを参照してください。

Quarkus アプリケーションがリバースプロキシー、ゲートウェイ、またはファイアウォールの背後で実行している場合は、HTTP Host ヘッダーが内部 IP アドレスにリセットされ、HTTPS 接続が終了するなどして、OIDC 認証メカニズムが影響を受ける可能性があります。たとえば、認可コードフローの redirect_uri パラメーターが、予期される外部ホストではなく内部ホストに設定されている場合があります。

このような場合は、プロキシーによって転送された元のヘッダーを認識するように Quarkus を設定する必要があります。詳細は、Vert.x ドキュメントの Running behind a reverse proxy セクションを参照してください。

たとえば、Quarkus エンドポイントが Kubernetes Ingress の背後にあるクラスターで実行している場合は、計算された redirect_uri パラメーターが内部エンドポイントアドレスを指している可能性があるため、OIDC プロバイダーからこのエンドポイントへのリダイレクトが機能しない可能性があります。この問題は、Kubernetes Ingress によって外部エンドポイントアドレスを表すように設定された X-ORIGINAL-HOST を使用する次の設定を使用して解決できます。

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-forwarded=false
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.forwarded-host-header=X-ORIGINAL-HOST

quarkus.oidc.authentication.force-redirect-https-scheme プロパティーは、Quarkus アプリケーションが SSL 終了リバースプロキシーの背後で実行している場合にも使用できます。

OIDC プロバイダーの外部からアクセス可能な認可、ログアウト、およびその他のエンドポイントは、quarkus.oidc.auth-server-url 内部 URL を基準として自動検出された URL または設定された URL とは異なる HTTP(S) URL を持つことができます。このような場合、エンドポイントは発行者の検証の失敗を報告し、外部からアクセス可能な OIDC プロバイダーエンドポイントへのリダイレクトが失敗する可能性があります。

Keycloak を使用する場合は、KEYCLOAK_FRONTEND_URL システムプロパティーを外部からアクセス可能なベース URL に設定して起動します。他の OIDC プロバイダーと連携する場合は、プロバイダーのドキュメントを確認してください。