Quarkus Security architecture

Quarkus Security 架构提供了多个内置认证机制，并且高度可自定义。在 Quarkus 中保护 HTTP 应用程序的主要机制是 @“28” 接口。

The Quarkus Security architecture provides several built-in authentication mechanisms and is highly customizable. The primary mechanism for securing HTTP applications in Quarkus is the HttpAuthenticationMechanism interface.

Overview of the Quarkus Security architecture

当客户端发送 HTTP 请求时，Quarkus 安全通过与多个内置核心组件的交互协调安全认证和授权，其中包括 HttpAuthenticationMechanism、IdentityProvider`和 `SecurityIdentityAugmentor。

When a client sends an HTTP request, Quarkus Security orchestrates security authentication and authorization by interacting with several built-in core components, including HttpAuthenticationMechanism, IdentityProvider, and SecurityIdentityAugmentor.

连续安全验证过程会产生三个结果之一：

The sequential security validation process results in one of three outcomes:

  • The HTTP request gets authenticated and authorized, and access to the Quarkus application gets granted.

  • The HTTP request authentication fails, and the requester receives a challenge specific to the authentication mechanism, for example, a 401 error, a URL redirect to reauthenticate, or some other custom authentication challenge response. For practical examples of challenge responses, see the Quarkus Security Tips and Tricks guide.

  • The HTTP request authorization fails, and the requester gets denied access to the Quarkus application.

下图介绍了 Quarkus 安全架构的详细流程：

The following diagram steps through the detailed process flow of the Quarkus Security architecture:

security architecture overview
Figure 1. The Quarkus Security architecture and process flow

Core components of the Quarkus Security architecture

HttpAuthenticationMechanism

Quarkus 安全使用 HttpAuthenticationMechanism`从 HTTP 请求中提取认证凭证，然后委托 `IdentityProvider`将凭证转换为 `SecurityIdentity。例如，凭证可能来自 `Authorization`标头、客户端 HTTPS 证书或 cookie。

Quarkus Security uses HttpAuthenticationMechanism to extract the authentication credentials from the HTTP request and delegates them to IdentityProvider to convert the credentials to SecurityIdentity. For example, the credentials can come from the Authorization header, client HTTPS certificates, or cookies.

当 Quarkus 安全拒绝认证请求时，`HttpAuthenticationMechanism`将认证挑战返回给客户端。挑战类型取决于认证机制。例如，使用 OIDC OpenID Connect (OIDC) 授权代码流机制，将生成重定向 URL，客户端返回到 OpenID Connect 提供程序进行认证。

When Quarkus Security rejects an authentication request, HttpAuthenticationMechanism returns an authentication challenge to the client. The type of challenge depends on the authentication mechanism. For example, with the OIDC OpenID Connect (OIDC) Authorization Code Flow mechanism, a redirect URL gets generated, and the client is returned to the OpenID Connect provider to authenticate.

IdentityProvider

IdentityProvider`验证认证凭证并将其映射到 `SecurityIdentity，其中包含用户名、角色、原始认证凭证和其他属性。

IdentityProvider verifies the authentication credentials and maps them to SecurityIdentity, which has the username, roles, original authentication credentials, and other attributes.

你可以为每个已认证资源注入一个 `SecurityIdentity`实例，获取已认证的身份信息。

You can inject a SecurityIdentity instance for every authenticated resource to get the authenticated identity information.

在其他上下文中，可能同时表示相同的某些信息或部分信息的平行表示形式，例如 Jakarta REST 的 SecurityContext`或 JSON Web 令牌 (JWT) 的 `JsonWebToken。

In other contexts, it is possible to have other parallel representations of the same information or parts of it, for example, SecurityContext for Jakarta REST or JsonWebToken for JSON Web Tokens (JWT).

有关更多信息，请参见 Quarkus Identity providers指南。

For more information, see the Quarkus Identity providers guide.

SecurityIdentityAugmentor

由于 Quarkus 安全是可自定义的，你还可以向 `SecurityIdentity`添加授权角色，并注册和优先考虑一个或多个 `SecurityAugmentor`实现。

Because Quarkus Security is customizable, you can, for example, add authorization roles to SecurityIdentity and register and prioritize one or more SecurityAugmentor implementations.

`SecurityIdentityAugmentor`的已注册实例在安全认证过程的最后阶段被调用。有关更多信息，请参见“安全提示与技巧”指南的 Security Identity Customization部分。

Registered instances of SecurityIdentityAugmentor are invoked during the final stage of the security authentication process. For more information, see the Security Identity Customization section of the "Security Tips and Tricks" guide.

Supported authentication mechanisms

Quarkus 安全框架支持多种认证机制，它们还可以组合在一起。某些受支持的认证机制内置于 Quarkus 中，而另一些则需要添加扩展。

The Quarkus Security framework supports multiple authentication mechanisms, which can also be combined. Some supported authentication mechanisms are built into Quarkus, while others require you to add an extension.

要了解 Quarkus 中的安全认证以及受支持的机制和协议，请参见 Quarkus Authentication mechanisms in Quarkus指南。

To learn about security authentication in Quarkus and the supported mechanisms and protocols, see the Quarkus Authentication mechanisms in Quarkus guide.

Proactive authentication

Quarkus 中默认启用主动认证。如果传入请求有凭证，即使目标网页不需要认证，请求也会始终被认证。有关更多信息，请参见 Quarkus Proactive authentication指南。

Proactive authentication is enabled in Quarkus by default. The request is always authenticated if an incoming request has a credential, even if the target page does not require authentication. For more information, see the Quarkus Proactive authentication guide.

Quarkus Security customization

Quarkus 安全是可自定义的。你可以自定义 Quarkus 的以下核心安全组件：

Quarkus Security is customizable. You can customize the following core security components of Quarkus:

  • HttpAuthenticationMechanism

  • IdentityProvider

  • SecurityidentityAugmentor

有关自定义 Quarkus 安全的更多信息，包括响应式安全和如何注册安全提供程序，请参见 Quarkus Security tips and tricks指南。

For more information about customizing Quarkus Security, including reactive security and how to register a security provider, see the Quarkus Security tips and tricks guide.

References