3.3. 集成注意事项

您可以检查在"OpenID Connect (OIDC) Bearer 令牌身份验证"指南的 单页应用程序 部分中建议采用单页应用程序(SPAs)是否满足您的要求。

如果您希望使用带有 Quarkus Web 应用程序的 SPAs 和 JavaScript API，如 Fetch 或 XMLHttpRequest(XHR)，请注意 OIDC 供应商可能不支持跨原始资源共享(CORS)进行授权端点，其中用户会在来自 Quarkus 的重定向后进行身份验证。如果 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，它将告知 Quarkus 如果当前请求是 JavaScript 请求。例如，如果 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"));
    }
}

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 状态代码中，重新加载最后请求页面。

否则，还必须更新浏览器脚本，以使用 JavaScript 值设置 X-Requested-With 标头，并在 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");
            }
         });
  }

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");
            }
         });
  }

如果您计划从在不同域上运行的单页应用消耗此应用，则需要配置跨原始资源共享(CORS)。如需更多信息，请参阅"Cross-origin 资源共享"指南中的 CORS 过滤器 部分。

如果您的 Quarkus 应用程序在反向代理、网关或防火墙后面运行，则 OIDC 身份验证机制可能会受到影响，当 HTTP 主机标头 可能会重置为内部 IP 地址，HTTPS 连接可能会被终止，以此类推。例如，授权代码流 redirect_uri 参数可能会设置为内部主机，而不是预期的外部。

在这种情况下，需要将 Quarkus 配置为识别代理转发的原始标头。如需更多信息，请参阅 反向代理 Vert.x 文档部分的运行。

例如，如果您的 Quarkus 端点在 Kubernetes Ingress 后面的集群中运行，则从 OIDC 供应商重新指向此端点的重定向可能无法正常工作，因为计算的 redirect_uri 参数可能指向内部端点地址。您可以使用以下配置来解决这个问题，其中 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.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 应用程序在 SSL 终止反向代理后面运行时，也可以使用 quarkus.oidc.authentication.force-redirect-https-scheme 属性。

与 URL 自动发现或配置相对于 quarkus.oidc.auth-server-url 内部 URL 相比，OIDC 供应商外部可访问的授权、注销和其他端点可以有不同的 HTTP (S) URL。在这种情况下，端点可能会报告签发者验证失败，并重定向到外部访问的 OIDC 供应商端点可能会失败。

如果您使用 Keycloak，那么使用 KEYCLOAK_FRONTEND_URL 系统属性将其启动，设置为外部可访问的基本 URL。如果使用其他 OIDC 供应商，请查看您的供应商文档。

防火墙后面的 OIDC 供应商可能会将 Quarkus OIDC HTTP 客户端的 GET 请求重定向到其某些端点，如已知的配置端点。默认情况下，Quarkus OIDC HTTP 客户端遵循 HTTP 重定向，不包括在重定向请求期间出于安全原因设置的 Cookie。

如果需要，您可以使用 quarkus.oidc.follow-redirects=false 禁用它。

当以下自动重定向被禁用，并且 Quarkus OIDC HTTP 客户端会收到重定向请求时，它将尝试只通过重定向 URI 恢复一次，但只有在重定向请求中设置了一个或多个 Cookie 时，只要重定向请求 URI 是完全一致的，只要重定向请求期间设置了一个或多个 Cookie。