3.3. 統合に関する考慮事項
OIDC によって保護されたアプリケーションは、シングルページアプリケーションから呼び出すことができる環境に統合されます。よく知られている OIDC プロバイダーと連携し、HTTP リバースプロキシーの背後で実行され、外部および内部アクセスを必要とするなど、さまざまな要件を満たす必要があります。
このセクションでは、これらの考慮事項を説明します。
3.3.1. シングルページアプリケーション
シングルページアプリケーション (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"); } }); }
3.3.2. Cross-Origin Resource Sharing
別のドメインで実行されているシングルページアプリケーションからこのアプリケーションを使用する予定の場合は、Cross-Origin Resource Sharing (CORS) を設定する必要があります。詳細は、"Cross-origin resource sharing" の CORS filter セクションを参照してください。
3.3.3. リバースプロキシーの背後で Quarkus アプリケーションを実行する
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 終了リバースプロキシーの背後で実行している場合にも使用できます。
3.3.4. OIDC プロバイダーへの外部および内部アクセス
OIDC プロバイダーの外部からアクセス可能な認可、ログアウト、およびその他のエンドポイントは、quarkus.oidc.auth-server-url
内部 URL を基準として自動検出された URL または設定された URL とは異なる HTTP(S) URL を持つことができます。このような場合、エンドポイントは発行者の検証の失敗を報告し、外部からアクセス可能な OIDC プロバイダーエンドポイントへのリダイレクトが失敗する可能性があります。
Keycloak を使用する場合は、KEYCLOAK_FRONTEND_URL
システムプロパティーを外部からアクセス可能なベース URL に設定して起動します。他の OIDC プロバイダーと連携する場合は、プロバイダーのドキュメントを確認してください。