Quarkus Security overview
Quarkus Security是一个框架，它提供了架构、多种认证和授权机制以及其他工具，用来为开发者提供构建达到生产级别安全性质量保证的Quarkus应用程序。
开始使用Quarkus Security
在您开始在您的Quarkus应用程序中建立安全机制之前，请回顾一下概述信息，了解Quarkus Security架构以及Quarkus支持的不同认证和授权机制。
To get started with security in Quarkus, we recommend that you first combine the Quarkus built-in Basic HTTP authentication with the JPA identity provider to enable role-based access control (RBAC). Complete the steps in the Secure a Quarkus application with Basic authentication tutorial. After you have successfully secured your Quarkus application with basic HTTP authentication, you can increase the security further by adding more advanced authentication mechanisms, for example, OpenID Connect (OIDC) authentication.
安全架构
HttpAuthenticationMechanism 接口是Quarkus 保护HTTP 程序安全的主要入口机制。
Quarkus Security使用 HttpAuthenticationMechanism 从HTTP请求中提取认证凭证，并委托给 IdentityProvider 来完成这些凭证到 SecurityIdentity 的转换。例如，凭证可能来自于HTTP Authorization 头、客户端HTTPS证书或cookies。
IdentityProvider 会验证认证凭证并将其映射到 SecurityIdentity ，其中包含用户名、角色、原始认证凭证和其他属性。
对于每个认证资源，您可以注入一个 SecurityIdentity 实例来获得认证的身份信息。
在其他一些情况下，您可能有相同信息或部分相同信息的其他不同表示，如JAX-RS的 SecurityContext ，或JWT的 JsonWebToken 。
认证机制
Quarkus supports multiple authentication mechanisms
Basic and Form HTTP authentication
Basic HTTP Authentication and Form HTTP authentication are the core authentication mechanisms supported in Quarkus.
WebAuthn认证机制
WebAuthn 是一种旨在取代密码的认证机制。简而言之，每当您写一个注册新用户或提供登录的服务，您就可以使用WebAuthn来代替使用密码的方式。更多信息，请参阅 使用WebAuthn 认证机制保护 Quarkus 应用程序.
TLS互认证
Quarkus provides mutual TLS (mTLS) authentication so that you can authenticate users based on their X.509 certificates. For more information, see mutual TLS authentication.
OpenID Connect authentication
OpenID Connect（OIDC）是一个身份层，它工作在OAuth 2.0协议之上。OIDC使客户端应用程序能够根据OIDC提供者进行的认证来验证用户的身份，并获取用户的基本信息。
quarkus-oidc 扩展提供了一个响应式的、可互操作的、支持多租户的OIDC适配器，以支持 Bearer Token 和 Authorization Code Flow 认证机制。Bearer Token 机制从HTTP header中提取token。 Authorization Code Flow 机制将用户重定向到OIDC提供者来认证用户身份，并在用户被重定向回Quarkus后，通过将提供的代码授权与ID、访问和刷新token进行交换来完成认证过程。
您可以使用可刷新的 JWK 密钥集验证ID和访问 JWT token。但JWT和不透明（二进制）token都可以被远程自省(introspect)。
|
通过 |
用于OIDC认证的其他Quarkus资源
关于可以应用于保护Quarkus程序的OIDC认证和授权的更多方式，请看以下更详细的资源：
| OIDC topic | Quarkus information resource |
|---|---|
Bearer Token authentication mechanism |
关于Bearer Token认证机制的信息，请参见 使用OpenID Connect保护应用程序服务 。 |
Authorization Code Flow authentication mechanism |
|
可支持 Bearer Token or Authorization Code Flow 机制的多租户模式s |
|
使用Keycloak进行集中授权 |
|
以编程方式配置Keycloak |
|
OpenID Connect client and filters
quarkus-oidc-client 扩展提供 OidcClient ，用于从支持以下token授权的OpenID Connect和OAuth2提供者那里获取和刷新访问token：
* client-credentials
* password
* refresh_token
quarkus-oidc-client-filter 扩展依赖于 quarkus-oidc-client 扩展，并提供 JAX-RS OidcClientRequestFilter ，它将由 OidcClient 获得的访问token设置为 HTTP Authorization 头的 Bearer scheme值。这个过滤器可以与注入当前 Quarkus 节点的 MP RestClient 实现一起被注册，但它与这个服务节点的认证要求无关。例如，它可以是一个公共节点，也可以用mTLS保护。
|
在这种情况下，您不需要通过使用Quarkus OpenID Connect适配器来保护您的Quarkus节点。 |
quarkus-oidc-token-propagation 扩展依赖于 quarkus-oidc 扩展，并提供 JAX-RS TokenCredentialRequestFilter ，它将 OpenID Connect Bearer 或 Authorization Code Flow 访问token设置为 HTTP Authorization 头的 Bearer scheme值。这个过滤器可以与注入当前 Quarkus 节点的 MP RestClient 实现一起被注册，并且Quarkus节点本身必须用Quarkus OpenID Connect适配器来保护。这个过滤器可以用来将访问token传播到下游服务中。
更多信息请参见《 使用OpenID Connect客户端和token传递quickstart 》和 《 link:security-openid-connect-client-reference.htmlOpenID Connect (OIDC) 和 OAuth2 客户端以及过滤器参考] 》指南。
SmallRye JWT authentication
quarkus-smallrye-jwt 提供Microprofile JWT 1.2.1的实现和更多的选项来验证签名和加密的 JWT token，并将其表示为 org.eclipse.microprofile.jwt.JsonWebToken。
quarkus-smallrye-jwt 提供了一个替代 quarkus-oidc Bearer Token认证机制的方法，并且目前只能验证使用PEM密钥或可刷新的 JWK 密钥集的 JWT token。此外，quarkus-smallrye-jwt 还提供了 JWT generation API`，以便轻松创建 signed 、 inner-signed 和 encrypted JWT token。
更多信息请参见《 使用SmallRye JWT RBAC 》指南。
OAuth2 认证机制
quarkus-elytron-security-oauth2 提供了一个替代 quarkus-oidc Bearer Token认证机制的方法。它基于 Elytron 并且主要是为了对不透明的token进行远程自我检查。更多信息请参见 使用OAuth2 指南。
在OpenID Connect、SmallRye JWT和OAuth2扩展之间做出选择
使用以下信息来帮助您决定使用哪种认证机制来保护您的Quarkus应用程序：
-
quarkus-oidc扩展需要一个OpenID Connect提供者，如Keycloak，用以验证Bearer tokens或用Authorization Code flow验证终端用户。在这两种情况下quarkus-oidc需要连接到这个OpenID Connect提供者。 -
如果用户认证需要是使用Authorization Code flow或者您需要支持多租户，请使用
quarkus-oidc。quarkus-oidc也可以通过Authorization Code Flow 和 Bearer access tokens来请求用户信息。 -
当需要验证Bearer tokens时，您可以使用
quarkus-oidc,quarkus-smallrye-jwt和quarkus-elytron-security-oauth2。 -
如果您有JWT格式的 Bearer tokens，那么这三个扩展都可以使用。
quarkus-oidc和quarkus-smallrye-jwt都支持在OpenID Connect提供者旋转密钥时刷新JsonWebKey（JWK）集，因此，如果必须避免远程token自查或提供者不支持，则应使用quarkus-oidc或quarkus-smallrye-jwt来验证JWTtoken。 -
如果您需要进行JWT tokens远程自查，您可以使用
quarkus-oidc或quarkus-elytron-security-oauth2，因为它们支持通过使用远程自查来验证不透明或二进制token。quarkus-smallrye-jwt不支持对不透明或JWT token进行远程自查，而是依赖于通常从OpenID Connect提供者那里检索的本地可用密钥。 -
quarkus-oidc和quarkus-smallrye-jwt支持将JWT和不透明的token都注入到节点代码中。注入的JWT token可以提供更丰富的用户信息。所有的扩展都可以将 token 以Principal的形式注入。 -
quarkus-smallrye-jwt比quarkus-oidc支持更多的密钥格式。后者只使用属于JWK集的JWK格式的密钥，反之前者还支持PEM密钥。 -
quarkus-smallrye-jwt不仅可以在本地处理有签名的 token ，而且还可以处理内部签名并加密(inner-signed-and-encrypted)和单纯加密的 token 。事实上，quarkus-oidc和quarkus-elytron-security-oauth2也可以验证这样的 token ，但只能把它们当作不透明的 token ，并通过远程自查来验证。 -
如果您需要一个轻量级的库来进行不透明或JWT token 的远程自查，请使用
quarkus-elytron-security-oauth2。
|
请注意，选择使用不透明 token 还是JWT token 格式通常是由架构考虑驱动的。不透明 token 通常比JWT token 短得多，但它们需要在提供者的数据库中维护大部分的 token 相关状态。不透明 token 实际上就是数据库指针。JWT token 比不透明 token 要长得多，但提供者通过将大部分 token 相关状态存储为 token 声明并对其进行签名或加密从而有效地将其委托给客户端。 |
下表提供了每种认证机制的选项摘要：
| quarkus-oidc | quarkus-smallrye-jwt | quarkus-elytron-security-oauth2 | |
|---|---|---|---|
需要进行Bearer JWT验证 |
本地验证或自查 |
本地验证 |
自查 |
需要进行不透明Bearer token验证 |
自查 |
不 |
自查 |
刷新 |
是 |
是 |
不 |
Represent token as |
是 |
是 |
是 |
将JWT注入为MP Json Web Token（JWT） |
是 |
是 |
不 |
Authorization Code Flow |
是 |
不 |
不 |
多租户 |
是 |
不 |
不 |
支持UserInfo |
是 |
不 |
不 |
支持Pem密钥格式 |
不 |
是 |
不 |
支持SecretKey |
不 |
以JsonWebKey (JWK) 格式 |
不 |
Inner-Signed/Encrypted 或 Encrypted tokens |
自查 |
本地验证 |
自查 |
自定义token验证 |
不 |
使用注入的JWT Parser |
不 |
接受JWT作为cookie |
不 |
是 |
不 |
身份提供者（Identity Providers）
JPA IdentityProvider 创建了一个 SecurityIdentity 实例，在用户认证过程中，它被用来验证和授权访问请求以保证您的Quarkus应用程序安全。
IdentityProvider 将 HttpAuthenticationMechanism 提供的认证凭证转换为 SecurityIdentity 实例。
一些扩展如 OIDC 、 OAuth2 以及 SmallRye JWT 有内联的 IdentityProvider 实现来针对支持的认证流程的。例如， quarkus-oidc 使用它自己的 IdentityProvider 来将token转换为 SecurityIdentity 实例。
如果您使用基于 Basic 或 Form HTTP的认证，那么您必须添加一个 IdentityProvider 实例，它可以将用户名和密码转换成 SecurityIdentity 实例。
-
关于基于
Basic或FormHTTP的认证的更多信息，请参阅一下资料：
授权
Quarkus also supports role-based access control (RBAC). For more information about RBAC and other authorization options in Quarkus, see Security authorization.
Quarkus Security customization
Quarkus Security是高度可定制的。您可以定制Quarkus的以下核心安全组件：
-
HttpAuthenticationMechanism -
IdentityProvider -
SecurityidentityAugmentor
关于定制Quarkus Security包括响应式Security的更多信息，以及如何注册一个安全提供者，请参见 安全定制 。
组合认证机制
如果用户证书是由不同的来源提供的，您可以使用组合认证机制。例如，您可以结合内置的 Basic 和 quarkus-oidc Bearer 认证机制。
|
但结合 |
特定路径认证机制
以下配置示例演示了如何强制要求对一个给定的请求路径选择一个认证机制：
quarkus.http.auth.permission.basic-or-bearer.paths=/service
quarkus.http.auth.permission.basic-or-bearer.policy=authenticated
quarkus.http.auth.permission.basic.paths=/basic-only
quarkus.http.auth.permission.basic.policy=authenticated
quarkus.http.auth.permission.basic.auth-mechanism=basic
quarkus.http.auth.permission.bearer.paths=/bearer-only
quarkus.http.auth.permission.bearer.policy=authenticated
quarkus.http.auth.permission.bearer.auth-mechanism=bearerauth-mechanism 属性值必须与 HttpAuthenticationMechanism 支持的认证方案相匹配，如 basic 或 bearer 或 form 等等。
主动认证
By default, Quarkus does proactive authentication, which means that all incoming requests with credentials are authenticated regardless of whether the target page requires authentication. For more information, see Proactive authentication.
使用SSL/TLS的安全连接
For more information about how Quarkus supports secure connections with SSL/TLS, see the HTTP reference information.
Cross-Origin 资源共享
如果您打算让您的Quarkus应用程序可以被运行在不同区域的另一个应用程序访问，您将需要配置CORS（Cross-Origin资源共享）。请阅读 TTP reference 以了解更多关于Quarkus所提供的CORS过滤器信息。
秘密引擎
秘密引擎是存储、生成或加密数据的组件。
Quarkus提供了非常全面的HashiCorp Vault支持，请参见 Quarkus和HashiCorp Vault 文档以了解更多信息。
安全序列化
如果您的Quarkus Security架构包含RESTEasy Reactive和Jackson时，Quarkus可以根据配置的安全性限制包含在JSON序列化中的字段。详情请参见 RESTEasy Reactive文档 。
Secure auto-generated resources by REST Data with Panache
If you’re using the REST Data with Panache extension to auto-generate your resources, you can still use the Security annotations within the package javax.annotation.security. For more information, see Securing auto-generated resources.
国家安全漏洞数据库
大多数Quarkus标签已经在美国 国家漏洞数据库 （NVD）中使用通用平台条目（Common Platform Enumeration，CPE）名称格式注册。所有注册的Quarkus CPE名称都可以通过 这个搜索查询 找到。
如果NVE数据库针对一个Quarkus tag标记了一个CVE，那么一个提供了这个CVE更多细节的链接就会被添加到给定的CPE名录下。
NVD CPE团队会定期更新列表，但如果您遇到一个异常，请在 quarkusio 仓库中创建一个issue来报告细节。
您可以通过使用Maven OWASP依赖性检查插件 在应用构建时用NVD feed来检测漏洞。
要在Quarkus Maven项目中添加OWASP依赖性检查插件，请在 pom.xml 文件中添加以下XML配置：
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
</plugin>|
Set the |
您可以像这样配置该插件：
<plugin>
<groupId>org.owasp</groupId>
<artifactId>dependency-check-maven</artifactId>
<version>${owasp-dependency-check-plugin.version}</version>
<configuration>
<!-- Fail only when detecting High Vulnerability issues -->
<failBuildOnCVSS>7</failBuildOnCVSS>
<suppressionFiles>
<suppressionFile>${project.basedir}/dependency-cpe-suppression.xml</suppressionFile>
</suppressionFiles>
</configuration>
</plugin>To detect less severe issues, adjust the value of failBuildOnCVSS to suppress the false positives, as demonstrated in the following code sample:
<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.2.xsd">
<!--
This is a CPE suppression file for the maven dependency check plugin.
Each CPE that is found by error (false positive) needs to be suppressed for a specific jar using its' GAV.
See https://jeremylong.github.io/DependencyCheck/general/suppression.html
-->
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for netty-tcnative-classes to netty
]]>
</notes>
<gav regex="true">^io\.netty:netty-tcnative-classes.*:.*$</gav>
<cpe>cpe:/a:netty:netty</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Quarkus Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.quarkus:quarkus-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:smallrye-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for Smallrye Mutiny to mutiny:mutiny
]]>
</notes>
<gav regex="true">^io\.smallrye.reactive:vertx-mutiny.*:.*$</gav>
<cpe>cpe:/a:mutiny:mutiny</cpe>
</suppress>
<suppress>
<notes>
<![CDATA[
Suppress the false positive CPE for graal-sdk to GraalVM (the JVM distribution)
]]>
</notes>
<gav regex="true">^org\.graalvm\.sdk:g like this
</suppress>
</suppressions>Ensure that you review and update the suppression list regularly to ensure that the results are up to date. You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example:
<suppress until="2022-01-01Z">…</suppress> You can adjust the expiry date if you need to.
Quarkus Security testing
当测试Quarkus Security的时候，请确保您已经在 application.properties 设置了 IdentityProvider 以及对应的用户名、密码以及角色。请参见 设置用户信息 以了解更多关于测试Quarkus Security的信息。
