Quarkus OpenId Connect (OIDC) 扩展配置参考

此构建时属性用于控制是否应启用整个 OIDC 扩展。如果在构建时禁用它，则 OIDC 扩展在运行时不可用。

Quarkus OIDC 租户配置表示与单个 OIDC 提供程序、多个 OIDC 提供程序租户或领域中的单个租户或领域相关的特定要求。

这两个属性允许指定是否应启用 OIDC 租户配置以及 OIDC 租户名称。

即使您使用单个默认 OIDC 租户，quarkus.oidc.tenant-enabled 属性也可能很有用，例如，当容器中的 OIDC 集成应仅在容器启动时激活时。

在大多数情况下，您不需要处理 quarkus.oidc.tenant-id 属性，除非您有多个 OIDC 租户配置要求并以编程方式创建 OIDC 租户配置。如果您在 application.properties 中配置 OIDC 租户，那么正如您从 OIDC 配置属性参考文档中看到的那样，租户 ID 被声明为租户特定属性组中的第三个令牌。

例如，以下配置设置了 OIDC tenant-1 配置要求

您可以配置或创建所需的任意数量的租户配置，并在请求时解析它们。

有关更多详细信息，请参阅多租户部分。

quarkus.oidc.auth-server-url 是一个关键的 OIDC 基本 URL 属性。默认情况下，Quarkus OIDC 会将 .well-known/openid-configuration 路径段添加到此 URL 并发现 OIDC 提供程序元数据。

当提供程序不支持元数据发现时（大多数 OAuth2 提供程序都不支持），或者当您想通过跳过远程发现调用来优化启动时间并改为配置单个 OIDC 提供程序端点 URL 时，可以使用 quarkus.oidc.discovery-enabled=false 禁用元数据发现。

当您需要覆盖发现的 OIDC 端点 URL 之一或当发现的 OIDC 元数据不包含必需的端点 URL 时，也可以设置单个 OIDC 端点 URL，例如 quarkus.oidc.authorization-path。

这些 URL 可以是相对于基本 quarkus.oidc.auth-server-url URL 的相对 URL，也可以是绝对 URL。

例如，通常在使用 OAuth2 提供程序时需要禁用发现并指定单个端点 URL，有关更多详细信息，请参阅 OAuth2 提供程序部分。

您可能需要配置的单个 OIDC 端点 URL 取决于 OIDC 应用程序类型和预期的令牌格式。

仅当启用 <<authorization-code-flow> 身份验证且 quarkus.oidc.application-type=web-app 时，quarkus.oidc.authorization-path、quarkus.oidc.token-path 和 quarkus.oidc.end-session-path 才相关。

quarkus.oidc.jwks-path 需要获取 JSON Web Key Set (JWKS)，但仅当令牌是 JSON Web Tokens (JWT) 时才需要。当 quarkus.oidc.application-type=web-app 时，表示用户身份验证的 ID 令牌始终采用 JWT 格式，并且在大多数情况下，需要 JWK 密钥来验证它们。如果您使用通常被远程自省的不透明（二进制）持有者访问令牌，则不需要 JWKS 路径。

在大多数情况下，当必须远程自省不透明（二进制）访问令牌时，需要 quarkus.oidc.introspection-path，因为此类令牌不能具有可以验证的附加签名。即使您使用 JWT 令牌并且您的提供程序支持远程令牌自省，也值得设置 quarkus.oidc.introspection-path。在这种情况下，当找不到匹配的 JWK 验证密钥来本地验证 JWT 时，可以远程自省 JWT 令牌作为回退。

通常在 <<authorization-code-flow> 完成后需要 quarkus.oidc.user-info-path，此时必须请求 UserInfo 以获取有关用户的更多信息，除了 ID 令牌中已有的信息。对于持有者访问令牌流程，也可以请求 UserInfo。

当您使用发布二进制访问令牌但不支持远程自省的 OAuth2 提供程序，并且没有标准的 UserInfo 支持时，quarkus.oidc.user-info-path 必须指向返回有关当前用户的 OAuth2 提供程序特定端点，以便支持间接访问令牌验证。有关更多详细信息，请参阅 OAuth2 提供程序部分。

Quarkus OIDC 当前不直接使用 quarkus.oidc.revoke-path 和 quarkus.oidc.registration-path。应用程序 可以在注销时撤销令牌以及其他安全事件。已经使用 quarkus-oidc 的应用程序可以使用 quarkus.oidc.registration-path 来 动态注册 OIDC 客户端。

但请记住，当您的提供程序支持元数据发现时，可以发现所有或部分这些 OIDC 端点特定 URL。

OIDC 应用程序类型确定如何对当前请求进行身份验证。

默认的 service 应用程序类型用于将 bearer 访问令牌与 HTTP Authorization: Bearer <token> 标头一起发送以访问 Quarkus 应用程序时。例如，Single-page application (SPA) 可以使用访问令牌代表当前登录的 SPA 用户访问 Quarkus。

当 quarkus-oidc 扩展使用 <<authorization-code-flow> 对用户进行身份验证到 Quarkus 并创建会话 cookie 时，使用 web-app 应用程序类型。

hybrid 应用程序类型可以用于同时支持持有者访问令牌和授权码流程。如果当前请求具有 HTTP Authorization: Bearer <token> 标头，则验证持有者访问令牌，否则，如果没有可用的会话 cookie，则用户将被重定向到 OIDC 提供程序进行身份验证。

quarkus-oidc 扩展表示已注册的 OIDC 应用程序客户端。此客户端需要在获取、自省或撤销令牌时向 OIDC 提供程序进行身份验证。

已注册的 OIDC 客户端具有客户端 ID，通常还具有客户端密钥。

当接受 JWT 持有者访问令牌时，quarkus.oidc.client-id 和 quarkus.oidc.credentials.secret 都是可选的，因为可以使用从公共 OIDC JWKS 密钥集端点获得的 JWK 验证密钥在本地验证它们。但是，无论如何，在这种情况下建议配置 quarkus.oidc.client-id，以使 OIDC 日志消息更具信息性。

quarkus.oidc.client-name 是一个用户友好的客户端名称，目前仅用于使日志消息更具信息性。

如果您启用 授权码流程身份验证，且 quarkus.oidc.application-type=web-app，则需要配置 quarkus.oidc.client-id 和 quarkus.oidc.credentials.secret（或其他类型的客户端凭据）才能完成当前授权码流程，因为 OIDC 令牌端点需要客户端身份验证。

如果必须自省令牌，则通常也需要这两个属性，无论持有者访问令牌还是授权码流程。

有关支持的 OIDC 提供程序客户端身份验证选项的完整说明，另请参阅 客户端身份验证选项部分。

当使用 quarkus.oidc.credentials.secret 配置客户端密钥时，它将与 quarkus.oidc.client-id 一起作为 HTTP Authorization: Basic 凭据对发送。但是，某些提供程序只能接受作为 POST 表单参数发送的客户端 ID 和密钥，此时您需要使用 quarkus.oidc.credentials.client-secret.method=post 配置。

quarkus.oidc.credentials.client-secret.provider.* 命名空间中的其余三个属性允许自定义如何使用自定义 CredentialsProvider 来提供存储在安全位置的密钥。或者，您可以使用 Quarkus 配置系统来管理密钥，请参阅 配置中的密钥指南。

Quarkus OIDC 可以不发送客户端密钥，而是通过发送使用客户端密钥或私钥签名的生成的 JWT 身份验证令牌向 OIDC 提供程序进行身份验证。

如果需要 MTLS 身份验证，请参阅 TLS 属性部分。

当必须自省令牌时，某些提供程序可能需要特定于自省的身份验证凭据，而不是已配置的 OIDC 客户端 ID 和 OIDC 客户端身份验证凭据之一

仅当您的提供程序需要特定于自省的身份验证凭据时，才必须使用 quarkus.oidc.introspection-credentials.name 和 quarkus.oidc.introspection-credentials.secret。在这种情况下，自省端点可能还需要作为 client_id 参数发送的 quarkus.oidc.client-id 属性。

目前，如果配置了自省凭据，则只能将其作为 HTTP POST 表单参数发送。

授权码流程的初始阶段（第一阶段）需要 Quarkus OIDC 构建正确的重定向 URL 并将用户重定向到 OIDC 提供程序进行身份验证。

quarkus.oidc.authentication.redirect-path 相对路径指向 Quarkus 端点，用户在完成身份验证挑战后，OIDC 提供程序会将用户重定向到该端点。此端点的绝对地址是您在 OIDC 应用程序注册期间设置为回调 URL 的地址。例如，如果 Quarkus 端点在 https://myservice.com 上运行，并且您具有 quarkus.oidc.authentication.redirect-path=service 重定向路径，则 https://myservice.com/service 是绝对回调 URL。

quarkus.oidc.authentication.response-mode 定义 OIDC 提供程序如何返回授权码流程属性，例如 code。通常，这些参数作为查询参数返回，例如，https://myservice.com/service?code=somecode&state=somestate。这是一种默认支持的 query 响应模式。

但是，此类参数也可能通过 POST 表单有效负载直接在请求正文中返回给 Quarkus。这是通过提供程序向用户返回 HTML 页面来实现的，并且此页面会自动将表单有效负载提交给 Quarkus。诸如 Apple 之类的某些提供程序可以强制执行此响应模式。如果需要支持此模式，请设置 quarkus.oidc.authentication.response-mode=form。另请注意，在这种情况下，无需设置 quarkus.oidc.authentication.remove-redirect-parameters=true，因为 code 和其他参数在请求正文中提交。

大多数 OIDC 提供程序都希望在初始重定向 URL 中使用 scope=openid 参数，并且 Quarkus 始终默认添加它自己，无需执行 quarkus.oidc.authentication.scopes=openid，但是通常您可能必须提供额外的范围或逗号分隔的范围列表，以便为一旦授权码流程完成，将颁发的访问令牌请求额外的权限（以及 ID 和刷新令牌）。例如，如果您需要 Quarkus 应用程序代表您读取您的 Google 日历，您可以执行 quarkus.oidc.authentication.scopes=https://www.googleapis.com/auth/calendar.readonly。

如果必须向 OIDC 提供程序提交多个范围，则使用`` 字符（URL 编码为 %20）来分隔多个范围值，例如，scope=openid%20scope=read。某些 OAuth2 提供程序，特别是 Strava OAuth2，期望使用逗号 , 分隔符，因此您可以执行 quarkus.oidc.authentication.scope-separator=,，等等。

如果 OAuth2 提供程序看到 openid 范围，则大多数 OAuth2 提供程序都会失败，但是大多数 OIDC 提供程序默认都期望此范围。这是可能必须设置 quarkus.oidc.authentication.add-openid-scope=false 的情况。

除了通常的 scope、redirect_uri 和 state 查询初始重定向参数之外，可能还必须包括其他参数，并且映射 quarkus.oidc.authentication.extra-params 属性可以提供帮助，例如，quarkus.oidc.authentication.extra-params.prompt=consent，等等。

quarkus.oidc.authentication.forward-params 映射参数可用于选择哪些原始用户请求 URL 的查询参数包含在 Quarkus 在重定向用户进行身份验证之前创建的重定向 URI 中。谨慎使用此属性。

当原始用户请求通过 HTTPS 发出，但防火墙终止了它并且 Quarkus 看到 http:// 方案时，可以使用 quarkus.oidc.authentication.force-redirect-https-scheme 构建正确的重定向 URI。通过设置 quarkus.oidc.authentication.force-redirect-https-scheme=true，您可以告诉 Quarkus 使用 https:// 方案，即使 Quarkus OIDC 在当前请求 URL 中看到 http:// 方案，以确保用户正确重定向到基于 HTTPS 的 OIDC 授权端点。如果您已经启用了 Quarkus 以识别 adoc:http-reference#reverse-proxy[转发或 X-Forwarded 标头]，则可能不需要设置此属性。

默认情况下，quarkus.oidc.authentication.allow-multiple-code-flows 允许多标签页身份验证。例如，用户在一个标签页中启动授权码流程，即将输入请求的凭据，由于某些中断而没有完成它，稍后打开另一个标签页并启动并完成另一个授权码流程，而原始流程仍在第一个标签页中挂起。现在，已经过身份验证的用户也返回到第一个标签页并完成它。如果这种身份验证流程灵活性被认为对您可能拥有的更严格的身份验证策略来说太多了，请设置 quarkus.oidc.authentication.allow-multiple-code-flows=false。另请参阅下面的 quarkus.oidc.authentication.fail-on-missing-kid 属性说明。

授权码流程的完成阶段（第二阶段）需要 Quarkus OIDC 将授权码交换为 ID、访问和刷新令牌。

quarkus.oidc.code-grant.extra-params 是一个映射属性，可用于设置必须发送到 OIDC 令牌端点才能完成授权码流程的额外参数，在用户经过身份验证并使用授权 code 重定向到 Quarkus 之后。通常，除了客户端身份验证凭据之外，此 code 和 redirect_uri（必须与初始授权码流程重定向中包含的 redirect_uri 匹配）都作为表单参数发送。

有时，还必须提供额外的 HTTP 标头才能完成授权码流程。在这种情况下，请使用 quarkus.oidc.code-grant.headers 映射属性。

quarkus.oidc.authentication.restore-path-after-redirect 可用于还原用于启动授权码流程的原始请求路径。例如，让我们假设您的应用程序提供了许多需要安全访问的端点，并且注册所有可能的初始安全 Quarkus 端点 URL 作为 OIDC 回调 URL 是不可能的。在这种情况下，可以设置 quarkus.oidc.authentication.restore-path-after-redirect=true，以使 Quarkus OIDC 在用户返回到使用 quarkus.oidc.authenticaion.redirect-path 配置的回调 URL 后，将经过身份验证的用户重定向到原始请求 URL。在这种情况下，回调 URL 预计是虚拟的，无需分配 JAX-RS 回调端点来支持它。

quarkus.oidc.authentication.remove-redirect-parameters 会在经过身份验证的用户重定向到 Quarkus 并且授权码已交换为令牌并建立了会话之后，强制执行额外的重定向。这样做是为了从 URL 中删除授权码流程特定属性，例如 code 和 state，如果应用程序不遵循其自己的重定向，则这些属性可能会在浏览器中仍然可见为 URL 查询参数。但请注意，code 是一次性令牌，只能由 Quarkus OIDC 交换，Quarkus OIDC 知道完成授权码流程所需的客户端凭据。但是，通常建议删除这些属性，并且应该默认这样做。

quarkus.oidc.authentication.nonce-required 是一种授权码流程安全强化属性，可以防止重放攻击。如果要求 Quarkus 在初始身份验证重定向期间生成它并包含 nonce=<generated_nonce> 查询参数，则 OIDC 提供程序必须返回一个 ID 令牌，其中包含具有匹配 nonce 值的 nonce 声明。默认情况下设置为 false，因为它不能保证所有 OIDC（尤其是 OAuth2）提供程序默认都支持它。如果您的提供程序支持此功能，建议将此属性设置为 true。

quarkus.oidc.authentication.pkce-required 可用于启用 Proof Key for Code Exchange (PKCE)。PKCE 主要适用于在浏览器中运行的公共 SPA OIDC 客户端。通常，Quarkus OIDC 充当机密 OIDC 客户端，可以向 OIDC 提供程序证明它知道客户端密钥，此时严格来说不需要 PKCE。但是，当您的提供程序对所有授权码流程客户端强制执行 PKCE 时，您可能必须启用它。

授权码流程完成后，Quarkus 可以访问 ID token，该令牌可以提供有关当前经过身份验证用户的足够信息。但是，通常，需要向 OIDC 提供程序的 UserInfo 端点发出额外的远程请求，以获取有关用户的更多详细信息。

quarkus.oidc.authentication.user-info-required 可用于启用额外的远程 UserInfo 请求。

当您使用纯 OAuth2 提供程序（例如 GitHub）时，始终需要设置 quarkus.oidc.authentication.user-info-required=true。原因是 OAuth2 不提供 ID token，而只提供 access token。仅在 OAuth2 世界中，访问令牌甚至不是为了当前客户端（即获取它的 Quarkus 端点）而设计的，而是为了此端点代表当前用户访问某些下游服务而设计的。但是 Quarkus 需要访问当前用户身份，因此在这种情况下必须设置此属性。但是由于 OAuth2 提供程序没有标准的 OIDC UserInfo 端点，因此必须将 quarkus.oidc.user-info-path 配置为指向返回有关当前用户的 OAuth2 提供程序特定端点，例如，在 GitHub 的情况下，它是 https://api.github.com/user。有关更多信息，请参阅 OAuth2 提供程序部分。

如果检测到 Quarkus 端点注入了 quarkus.oidc.UserInfo，则会自动启用 quarkus.oidc.authentication.user-info-required - 在这种情况下，您无需启用此属性。

如果必须 使用 UserInfo 验证访问令牌或使用不返回 ID 令牌但仅返回二进制访问令牌的 OAuth2 提供程序，则还自动启用此属性，必须使用 UserInfo 间接验证该二进制访问令牌，有关更多详细信息，请参阅 ID 令牌可用性部分。

授权码流程并非总是成功完成。用户可能会取消身份验证挑战，或者无法提供正确的凭据。在这种情况下，Quarkus 将返回 error 和 error_description 参数，而不是 code 参数。

当授权码流程失败时，默认情况下用户会收到 HTTP 401 状态错误，但是通过返回一个格式化的页面向用户解释发生了什么，可以提供更好的用户体验。您可以使用 quarkus.oidc.authentication.error-path 指向端点资源，该资源可以访问 Quarkus OIDC 转发给它的 error 和 error_description 参数，以创建这样的页面。

quarkus.oidc.authentication.fail-on-missing-state-param 用于控制当检测到状态 cookie 时应该发生什么，从而表明授权码流程的第一段即将完成，但是在预期从 OIDC 提供程序返回到 Quarkus OIDC 的重定向中，没有找到匹配的 state 查询参数。默认情况下，此属性设置为 false，因为在多标签身份验证中会出现这种情况，其中与一个标签相关的状态 cookie 可用，但当前请求表示新的标签身份验证请求（另请参见上面授权码流程启动部分中的 quarkus.oidc.authentication.allow-multiple-code-flows 属性描述）。它还使开发和测试 OIDC 安全端点变得更加容易，因为否则，在 OIDC 提供程序站点身份验证尝试失败或放弃后，尝试再次访问 Quarkus 可能会导致难以解释的 HTTP 401 状态错误，原因是丢失的状态 cookie，需要清理浏览器缓存。

quarkus.oidc.authentication.fail-on-missing-state-param=true 不会降低安全性，它主要关乎用户体验：如果由于缺少 state 查询参数而无法完成授权码流程，则用户将被重定向到 OIDC 提供程序以重新进行身份验证，而不是向用户返回空白的 HTTP 401 响应。

quarkus.oidc.authentication.fail-on-missing-kid 属性与多标签身份验证有关。可能会发生这种情况，即由于另一个标签中的身份验证导致验证密钥刷新，会话的 ID 令牌签名无法再被验证，并且找不到当前 ID 令牌的密钥标识符，从而导致 HTTP 401。要请求用户重新进行身份验证，您可以将此属性设置为 false。默认情况下，它设置为 true，以强调无法验证令牌签名的情况应谨慎对待。

当您使用 SPA 委托 Quarkus OIDC 管理授权码流程时，可以使用 quarkus.oidc.authentication.java-script-auto-redirect 来解决许多 OIDC 提供程序不支持对其身份验证端点的 CORS 的事实，这些端点使用身份验证屏幕来挑战用户。通过设置 quarkus.oidc.authentication.java-script-auto-redirect=true，您请求 Quarkus 返回 HTTP 499 状态，而不是 302 重定向，由于 OIDC 提供程序端此类重定向缺乏 CORS 支持，当此重定向由 SPA XHR 管理时，该重定向将被阻止。SPA 可以捕获 499 错误，并使用 window API 绕过浏览器脚本限制。

有关自定义 Java Script 请求检查的详细信息，请参见JavaScript 请求检查器部分。

OIDC 与 OAuth2 的不同之处在于，它添加了一种新的令牌类型，用于表示用户身份验证，即 ID 令牌。quarkus-oidc 与返回 ID 令牌的兼容 OIDC 提供程序一起使用，但也必须支持不返回它的 OAuth2 提供程序。使用 quarkus.oidc.authentication.id-token-required=false 告诉 Quarkus 您的提供程序无法提供所需的 ID 令牌。在这种情况下，Quarkus 会生成一个内部 ID 令牌来表示会话。Quarkus OIDC 还期望使用 quarkus.oidc.user-info-path 配置 OAuth2 提供程序特定的 UserInfo 端点路径，以获取有关当前用户的信息。

由于必须创建会话，但是 OAuth2 提供程序不返回可用于计算会话时长的 ID 令牌，因此可以使用 quarkus.oidc.authentication.internal-id-token-lifespan 持续时间属性来设置会话生存期。如果 OAuth2 服务器返回访问令牌 expires_in 属性，则如果未配置 quarkus.oidc.authentication.internal-id-token-lifespan，则此属性将用作会话时长属性。

常用 cookie 属性会影响授权码流程会话 cookie 和状态 cookie。

quarkus.oidc.authentication.cookie-path 和 quarkus.oidc.authentication.cookie-domain 属性控制状态 cookie 和会话 cookie 在哪些应用程序路径上可用。cookie-path 越宽（“/”），应用程序的安全空间就越大。您可能希望将其限制为更具体的路径，例如 /secured，以便更轻松地处理在诸如 /public 之类的路径上可用的公共空间。当特定端点路径只能由使用特定提供程序进行身份验证的用户访问时，您可能还希望对其进行限制。例如，/keycloak 路径只能由使用 Keycloak 进行身份验证的用户访问，/google - 使用 Google 等。有关更多信息，另请参见多租户部分。

quarkus.oidc.authentication.cookie-path-header 可用于动态设置所需的 cookie 路径 - 应谨慎使用此属性，并且仅当它适合您的部署要求时才使用。

默认情况下，quarkus.oidc.authentication.cookie-same-site 将 Same-Site 属性定义为 lax，因为将其设置为 strict 会破坏某些部署。但是，当已知它在您的部署中有效时，建议将其设置为 strict，例如，当 OIDC 提供程序与应用程序托管在同一域中时。

quarkus.oidc.authentication.cookie-suffix 可用于自定义状态 cookie 和会话 cookie 名称。例如，通过设置 %test.quarkus.oidc.authentication.cookie-suffix=test，您可以在测试配置文件中使会话 cookie 名称带有 _test 后缀。

如果 Quarkus 在非安全 HTTP 协议上侦听但在 HTTPS 终止反向代理后面运行，则 quarkus.oidc.authentication.cookie-force-secure 可能仅在某些部署中相关。如果 Quarkus 在 HTTPS 上侦听，则此属性没有影响，在这种情况下，cookie 始终是安全的。

Quarkus OIDC 创建一个状态 cookie，其值必须与在两次重定向期间在 Quarkus 和 OIDC 提供程序之间传递的 state 查询参数匹配。除了实际状态值之外，如果需要 ID 令牌包含 nonce 声明（使用 quarkus.oidc.authentication.nonce-required=true），并且如果需要使用证明密钥进行代码交换 (PKCE)（使用 quarkus.oidc.authentication.pkce-required=true），则状态 cookie 可能需要保留 nonce 值和 PKCE code-verifier。这两个值都必须加密。在这种情况下，状态 cookie 使用生成的密钥加密，但是您可以使用 quarkus.oidc.authentication.state-secret 提供您自己的状态 cookie 加密密钥，通常为 32 个字符长。

quarkus.oidc.authentication.state-cookie-age 定义了状态 cookie 的生存期。

在授权码流程完成后创建会话 cookie。可以刷新过期的会话 cookie。

当用户会话已过期并且刷新令牌可用时，可以使用 quarkus.oidc.token.refresh-expired 来启用自动用户会话续订。默认情况下不启用此属性，因为使用自动续订，用户在进行一次身份验证后，可能很长时间不会被要求重新进行身份验证。因此，可能需要管理员级别的决策来启用自动会话续订。

如果您希望用户在一段相当长的空闲时间后重新进行身份验证，请考虑配置 quarkus.oidc.authentication.session-expired-path，有关更多详细信息，请参见下文。

当 quarkus.oidc.token.refresh-expired 允许刷新时，可以使用 quarkus.oidc.token.refresh-token-time-skew 来强制刷新，并且会话 cookie 中的 ID 令牌仍然有效。如果仍然有效的 ID 令牌将在下一小时内过期，则可以使用此属性来请求刷新。如果您想自动刷新用户会话，则使用此属性可以最大限度地减少用户错过会话刷新的风险，如果会话 cookie 本身已过期并被浏览器删除。当您使用 SPA 时，您可以拥有一个后台线程定期 ping Quarkus，一旦 Quarkus 确定 ID 令牌将在配置的 quarkus.oidc.token.refresh-token-time-skew 时间段内很快过期，就会导致会话刷新。

例如，假设 ID 令牌的时长为 6 小时，因此会话 cookie 的时长也为 6 小时。如果用户在会话 cookie 即将过期前 1 小时访问了 Quarkus，然后空闲了 2 小时，那么在用户再次访问 Quarkus 时，这是在会话 cookie 创建后的 7 小时，也是在会话 cookie 和 ID 令牌过期并被浏览器删除后的 1 小时，Quarkus OIDC 只能请求用户重新进行身份验证，因为它无法再看到会话 cookie。为了最大限度地减少重新身份验证的尝试次数，请考虑延长会话时长，例如延长 3 小时。现在，假设最后一个示例，如果需要，Quarkus OIDC 仍然可以访问过期的 ID 令牌并对其执行一些有用的操作 - 刷新它或向用户提供会话过期页面，而不是立即请求新的身份验证。

如果配置了 quarkus.oidc.token.refresh-token-time-skew 属性，则会自动启用 quarkus.oidc.token.refresh-token 属性。

quarkus.oidc.authentication.session-expired-path 可用于向会话已过期的用户显示页面，该页面解释说会话已过期，并让用户单击链接以重新进行身份验证。它可以改善用户体验，因为否则，经过身份验证的用户（其会话已过期）在访问 Quarkus 应用程序时，在之前成功进行身份验证后经过一段延迟后，可能会对收到意外的 OIDC 提供程序的身份验证挑战屏幕感到惊讶。

有关管理会话 cookie 的更多信息，另请参见存储授权码流程令牌部分。

RP 启动的 注销涉及登录的用户通过调用应用程序注销端点来启动注销请求。Quarkus OIDC 截获此请求，清除会话 cookie，并将用户重定向到 OIDC 提供程序的注销端点。

quarkus.oidc.logout.path 是应该将用户注销请求发送到的相对路径。例如，给定 quarkus.oidc.logout.path=/logout，SPA 页面中的 注销 链接可以指向 https://:8080/logout。此路径可以是虚拟的，您无需创建在 /logout 上侦听的 JAX-RS 端点或路由处理程序。但是，为了使 quarkus.oidc.logout.path 有效，必须对其进行保护，有关更多详细信息，请参见用户启动的注销部分。

quarkus.oidc.logout.post-logout-path 指向一个公共端点，您希望提供程序将已注销的用户重定向到该端点。例如，可以使用 quarkus.oidc.logout.post-logout-path=/welcome.html 将已注销的用户返回到应用程序的欢迎页面，用户可以在该页面上选择再次登录。为了使注销后重定向生效，OIDC 提供程序通常需要注册绝对注销后 URL，例如 https://:8080/welcome.html。请不要忘记，它必须是一个公共端点，否则用户将在选择注销后立即被要求登录。

quarkus.oidc.logout.post-logout-uri-param 和 quarkus.oidc.logout.extra-params 可用于自定义 RP 启动的注销查询参数，例如，Auth0 可能会期望特定于 Auth0 的注销查询参数，有关更多详细信息，请参见用户启动的注销部分。

当需要支持全局注销时，后台通道注销应该用于涉及多个服务的复杂 Quarkus 应用程序，这些服务可能位于不同的主机或端口上。用户通过选择从其中一个服务注销，也会从所有其他服务注销。OIDC 提供程序检测来自其中一个服务的注销请求（例如，RP 启动的请求），并将后台通道通知发送到所有其他 Quarkus OIDC 应用程序。有关更多详细信息，请参见OIDC 后台通道注销部分。

请注意，支持后台通道注销选项需要管理挂起的后台通道通知的缓存。清除它们可能需要一段时间，因为它需要其后台通道注销处于挂起状态的用户才能访问 Quarkus。您的应用程序处理的用户越多，缓存大小就越大。

quarkus.oidc.logout.backchannel.path 是 OIDC 提供程序必须将后台通道注销通知发送到的相对路径。

后台通道通知包含一个注销令牌。必须缓存它，以便当其中一个经过身份验证的用户尝试访问 Quarkus 时，此用户的 ID 令牌可以与此注销令牌匹配。默认情况下，主题 (sub) 声明值用于匹配 ID 和注销令牌，但也可以使用会话 id (sid) 声明。

quarkus.oidc.logout.backchannel.token-cache-size、quarkus.oidc.logout.backchannel.token-cache-time-to-live 和 quarkus.oidc.logout.backchannel.clean-up-timer-interval 是用于管理后台通道通知缓存的属性。

前台通道注销在概念上与后台通道注销相似，但是通知通过浏览器转发到 Quarkus。有关更多详细信息，请参见OIDC 前台通道注销部分。

quarkus.oidc.logout.frontchannel.path 是浏览器将前台通道注销请求发送到的安全路径。

注销后，您可以请求 Quarkus OIDC 发送一个 Clear-Site-Data 响应标头，其中包含一个或多个指令，指示浏览器如何清除浏览器缓存。

可以配置 cache、client-hints、cookies、execution-contexts 和通配符 * 指令。

ID 令牌和访问令牌可能必须解密，或者必须对其标头进行预处理，才能开始并成功进行验证过程。

OIDC 提供程序通常会颁发已签名的 ID 令牌和访问令牌，但也可能会额外加密这些令牌，Quarkus 需要解密它们才能进行验证。选择必须解密的令牌类型：使用 quarkus.oidc.token.decrypt-id-token 的 ID 令牌，或者使用 quarkus.oidc.token.decrypt-access-token 的访问令牌。

如果 ID 令牌和访问令牌都包含用点字符分隔的 5 个部分，则认为它们已加密，这表明使用了 JWE 加密。

出于向后兼容性的原因，如果配置了 quarkus.oidc.token.decryption-key-location，则会尝试进行 ID 令牌解密，但是建议改用可选的 quarkus.oidc.token.decrypt-id-token 布尔属性，以允许更灵活地选择解密密钥。

当必须解密 ID 令牌或访问令牌时，首先检查 quarkus.oidc.token.decryption-key-location。如果未配置此属性，则使用JWT 客户端凭据密钥（如果可用）。最后，如果解密密钥仍未初始化，则将配置的客户端密钥用作解密密钥。

quarkus.oidc.token.customizer-name 是一个高级属性，可用于选择特定的 io.quarkus.oidc.TokenCustomizer 实现，该实现可以在验证其签名之前预处理 JWT 令牌标头。主要用例是支持验证旧版 Azure JWT 令牌，这些令牌必须重新计算其 nonce 标头才能成功进行签名验证。

令牌验证声明属性会影响核心令牌验证过程，其中令牌声明或内省属性必须满足特定的颁发者、受众、时长和其他限制。

建议强制令牌由特定颁发者颁发。当提供程序支持发现时，将发现令牌颁发者，否则可以将 quarkus.oidc.token.issuer 设置为特定值。

建议强制令牌用于特定受众。默认情况下，ID 令牌需要具有与 quarkus.oidc.client-id 属性匹配的受众值。对于持有者访问令牌，受众未标准化，例如，它们可以是表示目标端点的 URL。如果可能，持有者访问令牌也应限制为具有特定的受众值。

可以使用 quarkus.oidc.token.subject-required 来强制令牌具有唯一的主题值。如果您的提供程序为令牌分配了一个主题，那么需要它是一个不错的做法，尤其是在您处理多个 OIDC 和 OAuth2 提供程序并且想要获得唯一的用户标识符时。默认情况下未设置此属性，因为某些提供程序可能并不总是设置它。例如，Keycloak 轻量级访问令牌可能未设置主题 (sub) 声明。

当您必须处理不设置令牌 颁发时间 (iat) 声明的提供程序时，可以将 quarkus.oidc.token.issued-at-required 设置为 false。

quarkus.oidc.token.age 属性可用于强制规定令牌（否则有效）可以使用的时长。例如，某些提供程序可能会颁发有效期为几个月的令牌 - 如果您不希望您的用户能够使用有效期很长的访问令牌来访问 Quarkus 怎么办？在这种情况下，您可以将令牌时长设置为一些合理的值，例如 1 天等。

quarkus.oidc.token.lifespan-grace 属性应仅用于避免由于可能的时钟偏差导致的令牌验证失败。

当您知道提供程序设置了类型 (typ) 声明时，可以使用 quarkus.oidc.token.token-type 来强制执行令牌类型。例如，Keycloak 以 JWT 格式颁发 ID 令牌、访问令牌和刷新令牌，您如何防止 SPA 将 ID 令牌发送到 Quarkus，就像它是一个持有者访问令牌一样？设置 quarkus.oidc.token.token-type=bearer 强制仅接受包含类型 (typ) 声明且值为 bearer 的 JWT 访问令牌。

可以使用 quarkus.oidc.token.principal-claim 自定义应该使用哪个令牌声明来支持 Java Security Principal 和 MicroProfile JWT JsonWebToken API 来获取主体名称。upn、preferred_username、sub 是一些默认用于查找主体名称的声明，但是某些令牌可能在 name 或其他声明中包含该名称，这就是您可以设置 quarkus.oidc.token.principal-claim=name 等时。

可以使用 quarkus.oidc.token.required-claims 映射属性来提供一个额外的简单检查，以确保令牌包含特定的字符串声明值。

有关自定义 JWT 令牌验证的详细信息，另请参见Jose4 Validator 部分。

默认情况下，Quarkus 使用可用的验证密钥来验证 JWT 令牌签名，并使用 OIDC 提供程序和可用密钥集支持的任何非对称算法。例如，如果 JWK 集包含一个可以使用这两种算法验证使用 RSA 签名创建的公钥，则可以使用 RS256 或 PS256 算法签名的令牌。但是，您可能有一项策略要求仅使用特定的算法（例如 RS512） - 使用 quarkus.oidc.token.signature-algorithm=RS512 来强制执行它。

Quarkus OIDC 有一个 primary 令牌的概念。持有者访问令牌是一个主要令牌，因为它是唯一用于持有者访问令牌流程的令牌，并且外部客户端使用它来访问 Quarkus。持有者访问令牌始终被验证。ID 令牌是授权码流程中的一个主要令牌 - 它表示当前经过身份验证的用户。ID 令牌始终被验证。

代码流程访问令牌不是主要令牌，因为它并非用于访问已完成授权码流程的当前 Quarkus 应用程序。无论是 OIDC 还是 OAuth2，代码流程访问令牌都用于代表当前经过身份验证的用户访问另一个服务。例如，在身份验证重定向期间向提供程序发送 openid 范围会导致它颁发一个访问令牌，Quarkus 应用程序可以使用该令牌代表用户从此提供程序获取 UserInfo。

验证代码流程访问令牌是 OIDC 提供程序或此 Quarkus 应用程序需要使用代码流程访问令牌访问的下游 Quarkus 服务之一的工作。这是代码流程访问令牌通常作为二进制令牌提供的原因之一。

但是，如果您在设计应用程序时期望代码流程访问令牌（通常采用 JWT 格式）可以用作与您的应用程序相关的角色或其他信息的来源，请执行 quarkus.oidc.authentication.verify-access-token=true。如果 Quarkus 可以检测到应用程序代码中注入了没有 @IdToken 限定符的 JsonWebToken，则 Quarkus 会自动启用此属性，这表明应用程序打算访问代码流程访问令牌。

当传入的持有者访问令牌是二进制格式，或者当您使用 OAuth2 提供程序登录用户时，这些提供程序只提供 Quarkus 二进制访问令牌，并且在两种情况下都没有可用的远程自省端点，那么如何验证此二进制令牌？

唯一的选择是通过尝试使用此二进制令牌访问 OIDC 标准或 OAuth2 提供程序特定的 UserInfo 端点来间接验证访问令牌，因为有效的访问令牌必须转发到 UserInfo 端点。如果您的用例需要这样做，请设置 quarkus.oidc.token.verify-access-token-with-user-info=true。

另请参阅 OAuth2 提供程序 部分以获取更多信息。

当必须验证 JWT 令牌的签名时，此令牌的密钥标识符 (kid) 标头值用于从本地验证公钥集中查找匹配的 JWK 密钥。但是，由于提供程序倾向于定期回收签名密钥对，并开始使用新的私钥对新颁发的令牌进行签名，因此在某些时候，本地密钥集可能没有匹配的公钥来验证当前的 JWT。在这种情况下，Quarkus 会尝试刷新验证密钥集，但在 quarkus.oidc.token.forced-jwk-refresh-interval 时间段内阻止额外的 JWK 密钥集刷新尝试，以尽量减少许多随机令牌导致过多远程 JWK 集刷新尝试的风险。

某些 OIDC 提供程序支持远程令牌自省端点，如果 Quarkus 即使在刷新密钥集后也找不到匹配的 JWK 验证密钥，则会回退到自省 JWT 令牌。但是，仅仅因为提供程序支持自省端点，您的部署策略可能禁止远程 JWT 令牌自省：因为令牌可能具有敏感声明，或者出于性能原因，特别是如果您知道，例如，ID 令牌无法远程自省，只能使用 JWK 密钥在本地验证。如果您不希望将 JWT 令牌发送到远程自省，请设置 quarkus.oidc.token.allow-jwt-introspection=false。

另一方面，quarkus.oidc.token.require-jwt-introspection-only 强制只有 OIDC 提供程序本身才能决定当前 JWT 令牌是否有效，例如，为了立即识别当前令牌已被撤销等。在这种情况下，您也很可能会禁用发现，使用 quarkus.oidc.discovery-enabled=false，以防止 Quarkus 发现 JWKs 端点并获取无论如何都不会使用的验证密钥。

quarkus.oidc.token.allow-opaque-token-introspection 是一种加固类型的属性。Quarkus OIDC 默认尝试验证任何收到的访问令牌。但是，如果您处理 JWT 令牌，尤其是如果您更喜欢仅在本地使用 quarkus.oidc.token.allow-jwt-introspection=false 验证它们，那么如果有人发送您的应用程序实际上并不期望的二进制（不透明）访问令牌会怎样？设置 quarkus.oidc.token.allow-opaque-token-introspection=false 可以防止可能具有破坏性的远程自省调用，并在收到不透明令牌时立即导致验证错误。

默认情况下，令牌的 groups 数组声明预计包含角色。如果令牌是由 Keycloak 颁发的，则还会检查 realm_access/roles 和 realm_access/<client-id>/roles 声明。但是，如果令牌具有另一个包含角色的自定义声明，您可以使用 quarkus.oidc.roles.role-claim-path 指向它。它可用于选择顶级数组声明或使用 / 路径分隔符的嵌套声明。请确保对命名空间限定的声明名称使用双引号，例如，quarkus.oidc.roles.role-claim-path="http://auth0.customroles/roles"。

如果您想将 scope 声明视为角色来源，那么 scope 声明中的每个空格分隔的值都是角色名称。但是，包含多个角色值的字符串声明也可以用逗号 , 或其他字符分隔。在这种情况下，请使用 quarkus.oidc.roles.role-claim-separator=, 等。

主令牌默认是角色来源：在授权码流程中检查 ID 令牌中的角色，在持有者令牌流程中检查访问令牌中的角色。如果应用程序使用授权码流程，并且您需要检查访问令牌，而不是主 ID 令牌，那么您可以执行 quarkus.oidc.roles.source=access_token - 如果您处理持有者访问令牌，则无需设置此属性。

有时角色包含在 UserInfo 响应中 - 在这种情况下，执行 quarkus.oidc.roles.source=userinfo。

令牌绑定是用于发送方约束访问令牌的工具。

quarkus.oidc.token.binding.certificate=true 可用于将持有者访问令牌约束到正在发送它的 MTLS 客户端，如 RFC 8705：Mutual TLS 令牌绑定 规范中所述。

请参阅 Mutual TLS 令牌绑定 部分以获取更多信息。

另请参阅 持有者令牌标头 部分，了解有关启用 Demonstrating Proof of Posession (DPoP) 绑定的详细信息。

带有 Bearer 方案的 HTTP Authorization 标头通常用于发送持有者访问令牌。例如：Authorization: Bearer <token>。

在某些情况下，标头和方案可能都必须自定义。

quarkus.oidc.token.header 和 quarkus.oidc.token.authorization-scheme 可用于自定义哪个 HTTP 标头包含持有者访问令牌。您可以自定义标头，以及在使用 HTTP Authorization 时自定义方案。

例如，您可以设置 quarkus.oidc.token.authorization-scheme=DPoP 以接受作为 Authorization: DPoP <token> 发送的 DPoP 访问令牌。请参阅 Demonstrating Proof of Posession 部分以获取更多信息。

另请参阅 令牌绑定 部分。

远程令牌自省和 UserInfo 结果可以在多个请求之间共享，以避免一直为每个令牌执行远程自省和/或 UserInfo 调用。通过这样做，应用程序可能会错过即时令牌状态更改，例如，令牌可能已被撤销或停用，或者当前用户可能不再为颁发此令牌的组织工作，从而使缓存的令牌自省或 UserInfo 信息过时。因此，用户必须在仔细评估风险后才能启用与缓存令牌自省和 UserInfo 结果相关的属性。

Quarkus OIDC 为 所有 OIDC 租户提供默认令牌自省和 UserInfo 缓存。例如，如果您支持 GitHub 和 Strava OAuth2 身份验证，则 GitHib 和 Strava UserInfo 响应可以存储在同一个默认缓存中，并按 GitHib 或 Strava 访问令牌进行键控。默认情况下，此缓存已启用，使用 quarkus.oidc.default-token-cache-enabled 构建时属性，但除非您选择在此缓存中缓存令牌自省或 UserInfo 或两者都缓存，否则不会向其中添加任何条目。

quarkus.oidc.allow-token-introspection-cache 和 quarkus.oidc.allow-user-info-cache 可用于在 每个 OIDC 租户 的基础上启用缓存令牌自省和 UserInfo 结果。

quarkus.oidc.token-cache.max-size、quarkus.oidc.token-cache.time-to-live 和 quarkus.oidc.token-cache.clean-up-timer-interval 是用于管理默认令牌自省和 UserInfo 缓存的属性。

另请参阅 令牌自省缓存 和 UserInfo 缓存 部分，了解有关自定义令牌自省和 UserInfo 结果缓存的详细信息。

quarkus.oidc.cache-user-info-in-idtoken 是使用 OAuth2 提供程序时的一种可能的缓存优化选项，在这种情况下，会在会话 cookie 中生成并加密内部 ID 令牌。在这种情况下，UserInfo JSON 可以直接保存在生成的 ID 令牌中（在加密之前），从而避免了保留服务器端 UserInfo 缓存的需要。

在某些情况下，传入的 JWT 令牌根本没有匹配的验证密钥，并且无法自省。这些令牌只有一个 x5c 声明，其中包含带有可用于验证此令牌签名的公钥的证书链。例如，SCIM 配置代理、WebAuthn 系统可能会生成此类令牌。

Quarkus OIDC 无法使用令牌中嵌入的公钥，除非它证明应用程序信任包含此公钥的令牌证书链。

quarkus.oidc.certificate-chain.trust-store-file 必须可用，并且指向包含 至少 根证书的文件。quarkus.oidc.certificate-chain.trust-store-password 和 quarkus.oidc.certificate-chain.trust-store-file-type 可用于方便访问此信任存储。

quarkus.oidc.certificate-chain.trust-store-cert-alias 可用于选择特定的证书以匹配令牌的证书链根证书。

quarkus.oidc.certificate-chain.leaf-certificate-name 还可以要求信任存储包含叶链证书。

Quarkus OIDC 强制执行根证书匹配，并且还运行其他证书链检查，以确认链中的每个证书都没有过期，并且已由链中的下一个证书正确签名（根证书除外）。

另请参阅 证书链验证 部分，了解有关提供其他证书链检查的详细信息。

quarkus.oidc.public-key 可以包含嵌入的公共验证密钥，并用于 OIDC 测试。

您可以观察 Oidc 启动事件 并使用 OicTenantConfig 构建器 API 注册一个或多个 OIDC 租户。

您可以注册 TenantConfigResolver 并使用 OicTenantConfig 构建器 API 动态构建配置，使用请求属性（例如请求路径和标头）获取其他提示或从外部源检索匹配的配置。

当包含 quarkus-smallrye-health 依赖项时，可以使用此构建时属性来注册 OIDC 提供程序运行状况就绪性检查。注册运行状况检查后，它将使用 HTTP HEAD ping 每个配置的 OIDC 租户的知名 OIDC 提供程序配置端点。

单个 OIDC 租户状态为 OK、Not Ready、Disabled、Unknown 和 Error。

如果至少一个 OIDC 租户具有 OK 状态，则 OIDC 运行状况检查状态为 UP，否则为 DOWN。

您只需要一个属性即可开始支持持有者访问令牌

如果您的 OIDC 提供程序支持元数据发现，并且传入的持有者访问令牌是 JWT 格式，可以通过从提供程序的 JWK 端点获取的密钥进行验证，则此单个属性组合有效。

您无需配置任何内容即可开始使用持有者访问令牌 在开发模式下。

您需要四个属性才能开始使用授权码流程

如果您的 OIDC 提供程序支持元数据发现，则此属性组合有效。

通常，当您的应用程序安全空间大于单个 URL 时，您必须添加 redirect-path 属性以支持 OIDC 提供程序，这些提供程序要求只能注册特定的回调 URL，例如：quarkus.oidc.authentication.redirect-path=/callback。

您只需配置 quarkus.oidc.application-type=web-app 即可开始使用授权码流程 在开发模式下。

严格持有者访问令牌支持意味着强制声明（例如颁发者、受众和其他密钥声明）设置为特定值或可用。

严格授权码流程支持意味着强制声明（例如颁发者、受众和其他密钥声明）设置为特定值或可用。

严格的持有者访问令牌或授权码流程支持的构成在不同部署之间可能差异很大。例如，一个 OIDC 提供程序可能需要 MTLS 客户端身份验证，另一个可能需要 DPoP 绑定或 PKCE 支持。我们无法在本文档中涵盖太多组合。

如果您需要进一步的指导来创建更严格、更紧密的 OIDC 配置，我们将竭诚为您服务。请打开问题，并在 Quarkus Discussions、Zulip 用户频道上联系团队。

如上面的 令牌角色 部分所述，默认情况下使用令牌 groups 声明来检查身份角色，并且还可以使用配置选择包含角色的自定义声明。但是，可能需要额外的自定义和检查才能正确确定与当前令牌身份相关的角色和权限。

使用 io.quarkus.security.identity.SecurityIdentityAugmentor 来增强从主 ID 或访问令牌创建的身份。

另请参阅 HttpSecurityPolicy 和 PermissionChecker 部分，了解更多授权控制选项。

您可以注册 quarkus.oidc.TokenIntrospectionCache 提供程序来支持自定义令牌自省缓存实现，作为 令牌自省和 UserInfo 缓存 部分中描述的默认缓存实现的替代方案。

您可以注册 quarkus.oidc.UserInfoCache 提供程序来支持自定义 UserInfo 缓存实现，作为 令牌自省和 UserInfo 缓存 部分中描述的默认缓存实现的替代方案。

如 存储授权码流程令牌 部分中所述，Quarkus OIDC 已经为存储授权码流程令牌提供了无状态（默认）和有状态选项。您还可以提供自己的自定义 quarkus.oidc.TokenStateManager 实现。

您可以使用 OIDC 过滤器来观察对所有 OIDC 端点的请求和响应。

您还可以拦截 OIDC 重定向请求。

如 SPA 集成 部分中所述，Quarkus OIDC 可以返回错误以启动 SPA 的授权码流程，以拦截它并解决某些 OIDC 提供程序不支持授权端点的 CORS 这一事实。

对于 Quarkus OIDC 来说，要做到这一点，它需要知道请求是否来自 SPA。默认情况下，它会检查 X-Requested-With 请求标头，其值是否设置为 JavaScript 或 XMLHttpRequest 是否可用。

请参阅 与 SPA 集成 文档，了解有关使用自定义 quarkus.oidc.JavaScriptRequestChecker 请求检查器自定义 JavaScript 请求检查的更多信息。

注销 部分中描述的注销配置支持标准 OIDC 注销机制，Quarkus 端点与 OIDC 提供程序协调注销过程。有时，您可能只想执行 本地注销 来清除本地会话 cookie。

您可以观察与身份验证、注销等相关的 OIDC 事件。有关更多信息，请参阅 Listento OIDC 事件 部分。

如果您需要将当前的持有者或授权码流程访问令牌传播到下游服务，请使用 Quarkus OIDC 令牌传播功能。必须传播的令牌可以交换。

您可能需要撤销访问令牌，例如，在本地注销的情况下。有关更多信息，请参阅 令牌撤销 部分。