2025 年 3 月 19 日 #oidc #dpop #mtls

使用 Quarkus OIDC 发送者约束访问令牌

作者：Sergey Beryozkin

简介

单页应用程序 (SPA) 在浏览器中运行，并使用 OIDC 授权码流程登录用户，而不依赖于 Quarkus OIDC。身份验证完成后，SPA 会发送访问令牌代表已通过身份验证的用户访问 Quarkus。

请看一张简单的图表，展示了此过程的工作原理，该图表从 OIDC 承载令牌指南复制到此帖子中。

如上图所示，OIDC 提供商会对当前用户进行身份验证，SPA 会接收 ID 和访问令牌，并使用访问令牌访问 Quarkus 端点。

OAuth2 专家们一直在努力解决的安全挑战是：如何证明发送令牌的客户端（如 SPA）实际上拥有此令牌？HTTP Authorization: Bearer <token> 标头中没有任何内容可以证明 SPA 没有泄露该令牌。

多年来，出现了两个关于发送方约束访问令牌的规范：RFC 8705：双向 TLS 客户端身份验证和证书绑定的访问令牌和 RFC 9449：OAuth 2.0 证明持有能力 (DPoP)。

双向 TLS 客户端身份验证和证书绑定的访问令牌

双向 TLS 客户端身份验证和证书绑定的访问令牌规范描述了如何将访问令牌与 MTLS 客户端证书进行加密绑定。

通过证明访问令牌已绑定到客户端证书，Quarkus 应用程序可以高度确信当前的访问令牌已约束到通过 MTLS 向 Quarkus 进行身份验证的客户端，并且由该客户端拥有。

在这种情况下，实现加密绑定并不复杂。当前的访问令牌应包含一个与 SHA-256 证书指纹的确认，并且必须与当前 MTLS 客户端证书的指纹匹配。如果令牌是 JWT 格式，则必须包含一个确认声明。如果令牌是二进制格式，则必须在远程令牌内省响应中包含确认。

只有当 OpenId Connect 提供商能够访问在向 Quarkus 进行 MTLS 身份验证时使用的同一客户端证书时，此类绑定才能成功。

使用 MTLS 令牌绑定的缺点是，正确配置 OpenId Connect 提供商，确保浏览器在 SPA 将用户重定向到 OIDC 提供商进行身份验证时可以请求 X509 证书身份验证，这是复杂的。

如果您是 Keycloak 用户，请查看 Keycloak 服务器管理文档的“高级配置”部分中的“启用 OAuth 2.0 双向 TLS 证书绑定的访问令牌”，以及社区博文“如何将证书绑定的访问令牌与 Kong 和 Keycloak 一起使用”。

就 Quarkus 而言，除了 Vert.x HTTP MTLS 配置之外，您只需要设置一个 OIDC 配置属性 `quarkus.oidc.token.binding.certificate=true` 来强制执行 MTLS 令牌绑定。

有关更多详细信息，请参阅 Quarkus OIDC 双向 TLS 令牌绑定文档。

证明持有能力 (DPoP)

证明持有能力 (DPoP) 规范描述了如何将访问令牌与称为 DPoP 证明的特殊 JWT 令牌进行加密绑定。

SPA 客户端生成一对私钥和公钥，并创建一个 DPoP 证明令牌来完成从 OIDC 提供商获取访问令牌。然后，它将此 DPoP 令牌连同新的 DPoP 证明一起转发给 Quarkus。访问令牌必须通过包含一个公共 JSON Web 密钥 (JWK) 密钥指纹来绑定到 DPoP 证明，该指纹与 DPoP 证明中包含的公共 JWK 密钥指纹匹配。

只有当客户端使用相同的公钥和私钥对来创建 DPoP 证明以请求上一步中的访问令牌，并创建另一个 DPoP 证明将其与 DPoP 访问令牌一起提交给 Quarkus 时，此绑定才能成功。

Quarkus OIDC 还将强制执行其他 DPoP 证明检查要求。还计划支持自定义 DPoP 随机数提供程序。

与 MTLS 令牌绑定相比，DPoP 的采用预计会更快，因为 DPoP 是一个 `应用程序级别` 的协议，不期望进行传输级别的 MTLS 身份验证。但是，在 SPA 级别正确创建 DPoP 证明并不简单，需要谨慎。

如果您是 Keycloak 用户，启用实验性的 `dpop` 功能足以开始。还可以查看 Keycloak 服务器管理文档的“高级配置”部分中的“应用程序层的 OAuth 2.0 证明持有能力 (DPoP)”，以及社区博文“如何将证明持有能力 (DPoP) 令牌与 Kong 和 Keycloak 一起使用”。

就 Quarkus 而言，您只需要设置一个 OIDC 配置属性 `quarkus.oidc.token.authorization-scheme=dpop` 来接受 DPoP 令牌并强制执行它们与随附的 DPoP 证明的绑定。

有关更多详细信息，请参阅 Quarkus OIDC 证明持有能力 (DPoP) 文档。