2.2. 内置身份验证机制
Quarkus Security 提供以下内置身份验证支持:
2.2.1. 基本身份验证(Basic authentication) 复制链接链接已复制到粘贴板!
您可以使用内置 HTTP 基本身份验证机制保护 Quarkus 应用程序端点。如需更多信息,请参阅以下文档:
2.2.2. 基于表单的身份验证 复制链接链接已复制到粘贴板!
Quarkus 提供基于表单的身份验证,它们的工作方式类似于传统的 Servlet 形式的身份验证。与传统的形式身份验证不同,经过身份验证的用户不会存储在 HTTP 会话中,因为 Quarkus 不支持集群的 HTTP 会话。相反,身份验证信息存储在加密的 Cookie 中,可由共享同一加密密钥的所有群集成员读取。
要应用加密,请添加 quarkus.http.auth.session.encryption-key
属性,并确保您设置的值至少为 16 个字符。加密密钥使用 SHA-256 进行哈希处理。生成的摘要用作 Cookie 值的 AES-256 加密的密钥。Cookie 包含作为加密值的一部分的到期时间,因此集群中的所有节点都必须同步其时钟。在一分钟的间隔内,如果会话正在使用,则会使用更新的到期时间生成新的 Cookie。
要开始使用表单身份验证,您应该有类似的设置,如 启用基本身份验证和属性 quarkus.http.auth.form.enabled
所述,必须设置为 true
。
带有表单验证的简单 application.properties
类似如下:
在 application.properties 文件中配置用户名、secret 和角色只适用于测试场景。对于保护生产应用,使用数据库或 LDAP 存储此信息至关重要。如需更多信息,您可以查看 带有 Jakarta Persistence 的 Quarkus 安全性,或其他 启用基本身份验证 中所述。
应用程序登录页面将包含类似如下的 HTML 表单:
使用单页应用程序(SPA),您通常希望通过删除默认页面路径来避免重定向,如下例所示:
现在,您已为 SPA 禁用了重定向,您必须以编程方式从客户端登录并注销。以下是登录 j_security_check
端点的 JavaScript 方法示例,并通过销毁 Cookie 来注销应用。
要从客户端注销 SPA,cookie 必须设为 quarkus.http.auth.form.http-only-cookie=false
,以便您可以销毁 Cookie,并可能重定向到您的主页。
要从服务器注销 SPA,cookie 可以设置为 quarkus.http.auth.form.http-only-cookie=true
,并使用此示例代码销毁 Cookie。
- 1
- 通过删除会话 Cookie 来执行注销。
以下属性可用于配置基于表单的身份验证:
在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖
配置属性 | 类型 | default |
确定是否启用整个权限集。 默认情况下,如果定义了权限集,则会启用它。
环境变量: | 布尔值 | |
此权限集链接到的 HTTP 策略。 有三个内置策略:allow、deny 和 authenticated。可以定义基于角色的策略,扩展可以添加自己的策略。
环境变量: | string |
必需
|
此权限集的方法应用到。如果没有设置,则适用于所有方法。 请注意,如果请求与任何权限集中的任何路径匹配,但由于未列出方法,则请求将被拒绝。 方法特定权限优先于未设置任何方法的匹配项。 这意味着,如果 Quarkus 配置为允许 GET 和 POST 请求到 /admin,且没有将其他权限配置为 /admin 将被拒绝。
环境变量: | 字符串列表 | |
此权限检查应用到的路径。如果路径以 86] 结尾,则这被视为路径前缀,否则它将被视为完全匹配。 匹配会以长度为基础完成,因此最具体的路径匹配具有优先权。 如果多个权限集与同一路径匹配,那么显式方法匹配优先于设置方法,否则应用最严格的权限。
环境变量: | 字符串列表 | |
必须用来验证用户身份的路径特定身份验证机制。它需要匹配
环境变量: | string | |
表示除了具有获奖路径的策略外,此策略还始终适用于匹配的路径。避免创建多个共享策略,以最大程度降低性能影响。
环境变量: | 布尔值 |
|
权限检查是否应该应用到所有匹配路径,还是专用于 Jakarta REST 资源的路径。
环境变量: | All :适用于所有匹配路径。
jaxrs: Declares,权限检查必须仅应用于 Jakarta REST 请求路径。使用这个选项,延迟权限检查是否使用匹配的 Jakarta REST 端点上的注解选择验证机制。如果使用以下 REST 端点注解,则必须设置这个选项:- | all |
允许访问此策略保护的资源的角色。默认情况下,任何经过身份验证的用户都允许访问。
环境变量: | 字符串列表 |
|
根据
环境变量: | Map<String,List<String>> | |
如果成功应用此策略,则授予
环境变量: | Map<String,List<String>> | |
此策略授予的权限将通过此配置属性指定的
环境变量: | string |
|
将
例如,如果
环境变量: | Map<String,List<String>> | |
客户端证书属性,其值将根据证书属性文件中指定的角色映射映射到"安全Identity"角色。属性必须是 Relative Distinguished Names (RDN)或 Subject Alternative Names (SAN)之一。默认情况下,通用名称(CN)属性值用于角色映射。支持的值有:
环境变量: | string |
|
包含客户端证书属性值到角色映射的属性文件。只有在使用
属性文件预期具有
环境变量: | path | |
身份验证域
环境变量: | string | |
登录页面。可以通过设置
环境变量: | string |
|
用户名字段名称。
环境变量: | string |
|
密码字段名称。
环境变量: | string |
|
错误页面。可以通过设置
环境变量: | string |
|
如果没有保存的页面要重定向到,则要重定向到的登录页面。可以通过设置
环境变量: | string |
|
选项控制用于将用户重新定向到他们要访问的位置的 Cookie 名称。
环境变量: | string |
|
不活跃(空闲)超时 当达到不活跃超时时,cookie 不会更新,并会强制使用新的登录。
环境变量: |
| |
Cookie 在新的 Cookie 被更新超时替代之前如何获得,也称为"renewal-timeout"。 请注意,较小的值会导致服务器负载稍多(因为新加密的 Cookie 将更频繁生成);但是,较大的值会影响不活动超时,因为在生成 Cookie 时设置了超时。 例如,如果这设为 10 分钟,并且不活跃超时为 30m,如果用户的最后一个请求为 9m,则实际超时将在最后一次请求后发生 21m,因为仅在生成新 Cookie 时超时才会刷新。 也就是说,在服务器端不会跟踪超时;时间戳采用 Cookie 本身进行编码和加密,并通过每个请求进行解密和解析。
环境变量: |
| |
用于存储持久会话的 Cookie
环境变量: | string |
|
会话和位置 Cookie 的 Cookie 路径。
环境变量: | string |
|
设置 HttpOnly 属性,以防止通过 JavaScript 访问 Cookie。
环境变量: | 布尔值 |
|
会话和位置 Cookie 的 SameSite 属性。
环境变量: |
|
|
会话 Cookie 的 max-Age 属性。这是浏览器将保留 Cookie 的时间。 默认值为空,这意味着 Cookie 将保留,直到浏览器关闭为止。
环境变量: | ||
要求所有注册的 HTTP 身份验证机制都必须尝试验证请求凭据。
默认情况下,当 所有生成的安全身份都可以使用以下工具的方法检索: `io.quarkus.vertx.http.runtime.security.HttpSecurityUtils++#++getSecurityIdentities(io.quarkus.security.identity.SecurityIdentity)`
注入的
此属性默认为 false,这意味着当创建第一个 如果启用了特定于路径的身份验证,则此属性将被忽略。
环境变量: | 布尔值 |
|
包含的身份验证模式。
环境变量: | lax: 如果至少有一个注册的 HTTP 身份验证机制创建了身份,则身份验证会成功。
严格 :如果所有注册的 HTTP 身份验证机制都创建身份,则身份验证成功。通常,当凭证通过 mTLS 执行时,包含的身份验证应该处于严格的模式,当 mTLS 和另一个身份验证(如 OIDC bearer 令牌身份验证)时,必须成功。在这种情况下,由第一个机制 mTLS 创建的 | strict |
要写入持续时间值,请使用标准 java.time.Duration
格式。如需更多信息,请参阅 Duration#parse ()Java API 文档。
您还可以使用简化的格式,从数字开始:
- 如果值只是一个数字,它代表时间(以秒为单位)。
-
如果值为数字,后跟
ms
,代表时间(毫秒)。
在其他情况下,简化的格式被转换为 java.time.Duration
格式以进行解析:
-
如果该值是一个数字,后跟
h
、m
或s
,则前缀为PT
。 -
如果值为数字,后跟
d
,则会以P
为前缀。
2.2.3. 双向 TLS 身份验证 复制链接链接已复制到粘贴板!
Quarkus 提供 mutual TLS (mTLS)身份验证,以便您可以根据其 X.509 证书验证用户。
要使用此验证方法,您必须首先为应用程序启用 SSL/TLS。如需更多信息,请参阅 Quarkus "HTTP 参考" 指南中的支持使用 SSL/TLS 的安全连接 部分。
在应用程序接受安全连接后,下一步是使用保存应用程序信任的所有证书的 quarkus.http.ssl.certificate.trust-store-file
属性配置 quarkus.http.ssl.certificate.trust-store-file 属性。此文件还包含有关当客户端(如浏览器或其他服务)如何请求证书的信息,请尝试访问受保护的资源之一。
因为 JKS 不再是 Quarkus 中的默认密钥存储和信任存储格式,因此框架会根据文件扩展名进行 educated guess:
-
.pem
、.crt
和.key
显示为 PEM 证书和密钥。 -
.jks
、.keystore
、和.truststore
显示为 JKS 密钥存储和信任存储。 -
.p12
、.pkcs12
和.pfx
显示为 PKCS12 密钥存储和信任存储。
如果您的文件没有使用其中一个扩展,则必须使用以下属性设置格式:
quarkus.http.ssl.certificate.key-store-file-type=JKS # or P12 or PEM quarkus.http.ssl.certificate.trust-store-file-type=JKS # or P12 or PEM
quarkus.http.ssl.certificate.key-store-file-type=JKS # or P12 or PEM
quarkus.http.ssl.certificate.trust-store-file-type=JKS # or P12 or PEM
JKS 变得不常使用。从 Java 9 开始,Java 的默认密钥存储格式是 PKCS12。JKS 和 PKCS12 之间的显著区别在于 JKS 是特定于 Java 的格式。相反,PKCS12 是一种标准化、不中立的方式,用于存储加密的私钥和证书。
以下是启用 mTLS 的示例配置:
当传入请求与信任存储中的有效证书匹配时,您的应用程序可以通过注入 SecurityIdentity
获取主题,如下所示:
获取主题
您还可以使用以下示例中介绍的代码获取证书:
获取证书
import java.security.cert.X509Certificate; import io.quarkus.security.credential.CertificateCredential; CertificateCredential credential = identity.getCredential(CertificateCredential.class); X509Certificate certificate = credential.getCertificate();
import java.security.cert.X509Certificate;
import io.quarkus.security.credential.CertificateCredential;
CertificateCredential credential = identity.getCredential(CertificateCredential.class);
X509Certificate certificate = credential.getCertificate();
2.2.3.1. 将证书属性映射到角色 复制链接链接已复制到粘贴板!
来自客户端证书的信息可用于将角色添加到 Quarkus 安全Identity 。
在检查客户端证书的通用名称(CN)属性后,您可以将新角色添加到 SecurityIdentity
中。添加新角色的最简单方法是将证书属性用于角色映射功能。
例如,您可以更新部分中显示的属性,它引入了 Mutual TLS 身份验证,如下所示:
根据前面的配置,如果客户端证书的 CN 属性等于 alice
或 bob
,如果请求等同于 jdoe
,则请求被授权。
2.2.3.2. 使用证书属性来增强 SecurityIdentity 复制链接链接已复制到粘贴板!
如果 角色选项的自动映射证书属性不适用,则始终可以注册 SecurityIdentityAugmentor
。自定义 SecurityIdentityAugmentor
可以检查不同的客户端证书属性的值,并相应地增强 SecurityIdentity
。
有关自定义安全身份的更多信息,请参阅 Quarkus " 安全提示 和 tricks" 指南中的 安全身份自定义 部分。