2.2. 内置身份验证机制

Quarkus Security 提供以下内置身份验证支持：

2.2.1. 基本身份验证（Basic authentication）
复制链接

您可以使用内置的 HTTP 基本身份验证机制来保护 Quarkus 应用程序端点。如需更多信息，请参阅以下文档：

2.2.2. 基于表单的身份验证
复制链接

Quarkus 提供基于表单的身份验证，其的工作方式类似于传统的 Servlet 基于表单的身份验证。与传统的表单身份验证不同，经过身份验证的用户没有存储在 HTTP 会话中，因为 Quarkus 不支持集群的 HTTP 会话。相反，身份验证信息存储在加密的 cookie 中，该 Cookie 可以被共享同一加密密钥的所有群集成员读取。

要应用加密，请添加 quarkus.http.auth.session.encryption-key 属性，并确保您设置的值至少为 16 个字符。使用 SHA-256 对加密密钥进行哈希处理。生成的摘要用作 Cookie 值的 AES-256 加密的密钥。Cookie 包含作为加密值一部分的过期时间，因此集群中的所有节点都必须同步其时钟。一分钟内，如果会话正在使用，则使用更新的到期时间生成一个新的 Cookie。

使用单页应用程序(SPA)时，您通常希望通过删除默认页面路径来避免重定向，如下例所示：

do not redirect, respond with HTTP 200 OK
do not redirect, respond with HTTP 401 Unauthorized
HttpOnly must be false if you want to log out on the client; it can be true if logging out from the server

# do not redirect, respond with HTTP 200 OK
quarkus.http.auth.form.landing-page=

# do not redirect, respond with HTTP 401 Unauthorized
quarkus.http.auth.form.login-page=
quarkus.http.auth.form.error-page=

# HttpOnly must be false if you want to log out on the client; it can be true if logging out from the server
quarkus.http.auth.form.http-only-cookie=false

Copy to Clipboard

Toggle word wrap

现在，您已禁用了 SPA 的重定向，您必须以编程方式从客户端注销。以下是用于登录 j_security_check 端点并通过销毁 cookie 注销应用的 JavaScript 方法示例。

const login = () => {
    // Create an object to represent the form data
    const formData = new URLSearchParams();
    formData.append("j_username", username);
    formData.append("j_password", password);

    // Make an HTTP POST request using fetch against j_security_check endpoint
    fetch("j_security_check", {
        method: "POST",
        body: formData,
        headers: {
            "Content-Type": "application/x-www-form-urlencoded",
        },
    })
    .then((response) => {
        if (response.status === 200) {
            // Authentication was successful
            console.log("Authentication successful");
        } else {
            // Authentication failed
            console.error("Invalid credentials");
        }
    })
    .catch((error) => {
        console.error(error);
    });
};

const login = () => {
    // Create an object to represent the form data
    const formData = new URLSearchParams();
    formData.append("j_username", username);
    formData.append("j_password", password);

    // Make an HTTP POST request using fetch against j_security_check endpoint
    fetch("j_security_check", {
        method: "POST",
        body: formData,
        headers: {
            "Content-Type": "application/x-www-form-urlencoded",
        },
    })
    .then((response) => {
        if (response.status === 200) {
            // Authentication was successful
            console.log("Authentication successful");
        } else {
            // Authentication failed
            console.error("Invalid credentials");
        }
    })
    .catch((error) => {
        console.error(error);
    });
};

Copy to Clipboard

Toggle word wrap

要从客户端注销 SPA，cookie 必须设置为 quarkus.http.auth.form.http-only-cookie=false，以便您可以销毁 cookie，并可能重定向到您的主页面。

const logout= () => {
    // delete the credential cookie, essentially killing the session
    const removeCookie = `quarkus-credential=; Max-Age=0;path=/`;
    document.cookie = removeCookie;

    // perform post-logout actions here, such as redirecting back to your login page
};

const logout= () => {
    // delete the credential cookie, essentially killing the session
    const removeCookie = `quarkus-credential=; Max-Age=0;path=/`;
    document.cookie = removeCookie;

    // perform post-logout actions here, such as redirecting back to your login page
};

Copy to Clipboard

Toggle word wrap

要从服务器的 SPA 注销，可以将 Cookie 设置为 quarkus.http.auth.form.http-only-cookie=true，并使用此示例代码销毁 Cookie。

@ConfigProperty(name = "quarkus.http.auth.form.cookie-name")
String cookieName;

@Inject
CurrentIdentityAssociation identity;

@POST
public Response logout() {
    if (identity.getIdentity().isAnonymous()) {
        throw new UnauthorizedException("Not authenticated");
    }
    final NewCookie removeCookie = new NewCookie.Builder(cookieName)
            .maxAge(0)
            .expiry(Date.from(Instant.EPOCH))
            .path("/")
            .build();
    return Response.noContent().cookie(removeCookie).build();
}

@ConfigProperty(name = "quarkus.http.auth.form.cookie-name")
String cookieName;

@Inject
CurrentIdentityAssociation identity;

@POST
public Response logout() {
    if (identity.getIdentity().isAnonymous()) {
        throw new UnauthorizedException("Not authenticated");
    }
    final NewCookie removeCookie = new NewCookie.Builder(cookieName)
            .maxAge(0)
            .expiry(Date.from(Instant.EPOCH))
            .path("/")
            .build();
    return Response.noContent().cookie(removeCookie).build();
}

Copy to Clipboard

Toggle word wrap

以下属性可用于配置基于表单的身份验证：

lock 构建时修复的配置属性 - 所有其他配置属性可在运行时覆盖

Expand

Configuration 属性

类型

default

lock quarkus.http.auth.form.enabled

如果启用了表单身份验证。

环境变量： QUARKUS_HTTP_AUTH_FORM_ENABLED

布尔值

false

lock quarkus.http.auth.form.post-location

后位置。

环境变量： QUARKUS_HTTP_AUTH_FORM_POST_LOCATION

string

/j_security_check

lock 构建时修复的配置属性 - 所有其他配置属性可在运行时覆盖

Expand

Configuration 属性	类型	default
`quarkus.http.auth.certificate-role-properties` 包含客户端证书通用名称(CN)到角色映射的属性文件。仅在使用 `quarkus.http.ssl.client-auth=required` 或 `quarkus.http.ssl.client-auth=request` 启用 mTLS 身份验证机制时才使用它。属性文件应该具有 `CN=role1,role,…,roleN` 格式，应该使用 UTF-8 进行编码。环境变量： `QUARKUS_HTTP_AUTH_CERTIFICATE_ROLE_PROPERTIES`	path
`quarkus.http.auth.realm` 身份验证域环境变量： `QUARKUS_HTTP_AUTH_REALM`	string
`quarkus.http.auth.form.login-page` 登录页面。可以通过设置 `quarkus.http.auth.form.login-page=` 来禁用重定向到登录页面。环境变量： `QUARKUS_HTTP_AUTH_FORM_LOGIN_PAGE`	string	`/login.html`
`quarkus.http.auth.form.username-parameter` username 字段名称。环境变量： `QUARKUS_HTTP_AUTH_FORM_USERNAME_PARAMETER`	string	`j_username`
`quarkus.http.auth.form.password-parameter` password 字段名称。环境变量： `QUARKUS_HTTP_AUTH_FORM_PASSWORD_PARAMETER`	string	`j_password`
`quarkus.http.auth.form.error-page` 错误页面。可以通过设置 `quarkus.http.auth.form.error-page=` 来禁用重定向到错误页面。环境变量： `QUARKUS_HTTP_AUTH_FORM_ERROR_PAGE`	string	`/error.html`
`quarkus.http.auth.form.landing-page` 如果没有要重新重定向到的保存页面，则要重定向到的登录页面。可以通过设置 `quarkus.http.auth.form.landing-page=` 来禁用登录页面。环境变量： `QUARKUS_HTTP_AUTH_FORM_LANDING_PAGE`	string	`/index.html`
`quarkus.http.auth.form.location-cookie` 控制用于重定向用户要访问的位置的 Cookie 名称的选项。环境变量： `QUARKUS_HTTP_AUTH_FORM_LOCATION_COOKIE`	string	`quarkus-redirect-location`
`quarkus.http.auth.form.timeout` 达到不活跃超时时不活动（空闲）超时，Cookie 不会被续订，并强制进行新的登录。环境变量： `QUARKUS_HTTP_AUTH_FORM_TIMEOUT`	duration	`PT30M`
`quarkus.http.auth.form.new-cookie-interval` Cookie 在被替换为更新超时的新 Cookie 之前可以如何替换它，也称为"renewal-timeout"。请注意，较小的值会稍微多于服务器负载（因为新的加密 Cookie 将更频繁地生成）；但是，较大的值会影响不活动超时，因为在生成 Cookie 时设置了超时。例如，如果将其设置为 10 分钟，并且不活跃超时为 30m，如果用户的最后请求是 Cookie，则实际超时会在最后一次请求后发生 21m，因为仅在生成新 Cookie 时刷新超时。也就是说，服务器端不会跟踪超时；时间戳在 Cookie 本身中经过编码和加密，并且会为每个请求解密并解析。环境变量： `QUARKUS_HTTP_AUTH_FORM_NEW_COOKIE_INTERVAL`	duration	`PT1M`
`quarkus.http.auth.form.cookie-name` 用于存储持久会话的 Cookie 环境变量： `QUARKUS_HTTP_AUTH_FORM_COOKIE_NAME`	string	`quarkus-credential`
`quarkus.http.auth.form.cookie-path` 会话和位置 Cookie 的 Cookie 路径。环境变量： `QUARKUS_HTTP_AUTH_FORM_COOKIE_PATH`	string	`/`
`quarkus.http.auth.form.http-only-cookie` 设置 HttpOnly 属性，以防止通过 JavaScript 访问 Cookie。环境变量： `QUARKUS_HTTP_AUTH_FORM_HTTP_ONLY_COOKIE`	布尔值	`false`
`quarkus.http.auth.form.cookie-same-site` 会话和位置 Cookie 的 SameSite 属性。环境变量： `QUARKUS_HTTP_AUTH_FORM_COOKIE_SAME_SITE`	`strict`,`lax`,`none`	`strict`
`quarkus.http.auth.permission."permissions"` 确定是否启用整个权限集。默认情况下，如果定义了权限集，它会被启用。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__ENABLED`	布尔值
`quarkus.http.auth.permission."permissions"` 此权限集链接到的 HTTP 策略。有三个内置策略：allow、deny 和 authentication。可以根据角色的策略定义，扩展也可以添加自己的策略。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__POLICY`	string	必需
`quarkus.http.auth.permission."permissions"` 此权限集应用到的方法。如果没有设置，则它们适用于所有方法。请注意，如果请求与任何权限集的路径匹配，但由于未列出方法，不匹配约束，则请求将被拒绝。特定于方法的权限优先于没有设置任何方法的匹配项。这意味着，例如，如果 Quarkus 配置为允许 GET 和 POST 请求发送到 /admin，且没有将 PUT 请求配置为 /admin，则拒绝将 PUT 请求配置为 /admin。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__METHODS`	字符串列表
`quarkus.http.auth.permission."permissions"` 此权限检查应用到的路径。如果路径以 VRF 结尾，则它将被视为路径前缀，否则它将被视为完全匹配。匹配按长度进行，因此最具体的路径匹配具有优先权。如果多个权限集与同一路径匹配，则显式方法匹配优先于没有设置方法的匹配项，否则会应用限制性最强的权限。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__PATHS`	字符串列表
`quarkus.http.auth.permission."permissions".auth-mechanism` 特定于路径的验证机制，必须用于验证用户。它需要匹配 `HttpCredentialTransport` 身份验证方案，如 'basic'、'bearer'、'form' 等。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__AUTH_MECHANISM`	string
`quarkus.http.auth.permission."permissions"` 表示此策略总是适用于匹配的路径，除了具有获奖路径的策略之外。避免创建多个共享策略，以最大程度降低性能影响。环境变量： `QUARKUS_HTTP_AUTH_PERMISSION__PERMISSIONS__SHARED`	布尔值	`false`
`quarkus.http.auth.policy."role-policy".roles-allowed` 允许访问此策略保护的资源的角色。默认情况下，允许访问任何经过身份验证的用户。环境变量： `QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__ROLES_ALLOWED`	字符串列表	`**`
`quarkus.http.auth.policy."role-policy".roles` 根据 `SecurityIdentity` 已具有的角色，为 `SecurityIdentity` 添加授予的角色。例如，Quarkus OIDC 扩展可以从验证的 JWT 访问令牌中映射角色，您可能希望将其重新映射到部署特定的角色。环境变量： `QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__ROLES`	`Map<String,List<String>>`
`quarkus.http.auth.policy."role-policy".permissions` 如果此策略成功应用，则授予 `SecurityIdentity` 的权限（策略允许请求继续），并且经过身份验证的用户需要角色。例如，您可以通过设置 `quarkus.http.auth.policy.role-policy1.permissions. admin =perm1:action1,perm1: action2 配置属性，将权限 perm1 映射到角色 admin`。授予的权限用于带有 `@PermissionsAllowed` 注释的授权。环境变量： `QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__PERMISSIONS`	`Map<String,List<String>>`
`quarkus.http.auth.policy."role-policy".permission-class` 此策略授予的权限将使用此配置属性指定的 `java.security.Permission` 实现创建。权限类必须准确声明一个构造器，它接受权限名称(`字符串`)或权限名称和操作(`字符串`,`String[]`)。如果您以原生模式运行应用程序，则必须注册权限类来反映。环境变量： `QUARKUS_HTTP_AUTH_POLICY__ROLE_POLICY__PERMISSION_CLASS`	string	`io.quarkus.security.StringPermission`

关于 Duration 格式

要写入持续时间值，请使用标准的 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.key-store-file=server-keystore.jks            
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks        
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required                                      
quarkus.http.auth.permission.default.paths=/*                              
quarkus.http.auth.permission.default.policy=authenticated
quarkus.http.insecure-requests=disabled

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks


quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks


quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required


quarkus.http.auth.permission.default.paths=/*


quarkus.http.auth.permission.default.policy=authenticated
quarkus.http.insecure-requests=disabled

Copy to Clipboard

Toggle word wrap

1: 服务器私钥所在的密钥存储。
2: 加载可信证书的信任存储。
3: 将值设为 required 时，服务器需要客户端证书。将值设为 REQUEST 以允许服务器在没有证书的情况下接受请求。当支持 mTLS 之外的验证方法时，此设置很有用。
4: 定义策略，其中只有经过身份验证的用户应该可以从应用程序访问资源。
5: 您可以明确禁用普通 HTTP 协议，从而要求所有请求都使用 HTTPS。当您将 quarkus.http.ssl.client-auth 设置为 required 时，系统会自动将 quarkus.http.insecure-requests 设置为 disabled。

当传入的请求与信任存储中的有效证书匹配时，应用程序可以通过注入 SecurityIdentity 来获取主题，如下所示：

获取主题

@Inject
SecurityIdentity identity;

@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
    return String.format("Hello, %s", identity.getPrincipal().getName());
}

@Inject
SecurityIdentity identity;

@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
    return String.format("Hello, %s", identity.getPrincipal().getName());
}

Copy to Clipboard

Toggle word wrap

您还可以使用以下示例中介绍的代码获取证书：

获取证书

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();

Copy to Clipboard

Toggle word wrap

2.2.3.1. 将证书属性映射到角色
复制链接

客户端证书的信息可用于将角色添加到 Quarkus SecurityIdentity。

在检查客户端证书的通用名称(CN)属性后，您可以在 SecurityIdentity 中添加新角色。添加新角色的最简单方法是使用 certificate 属性到角色映射功能。

例如，您可以更新部分中显示的属性，它引入了 Mutual TLS 身份验证，如下所示：

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required
quarkus.http.insecure-requests=disabled

quarkus.http.auth.certificate-role-properties=cert-role-mappings.properties 

quarkus.http.auth.permission.certauthenticated.paths=/*   
quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert 
quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required
quarkus.http.insecure-requests=disabled

quarkus.http.auth.certificate-role-properties=cert-role-mappings.properties



quarkus.http.auth.permission.certauthenticated.paths=/*


quarkus.http.auth.permission.certauthenticated.policy=role-policy-cert


quarkus.http.auth.policy.role-policy-cert.roles-allowed=user,admin

Copy to Clipboard

Toggle word wrap

1: cert-role-mappings.properties classpath 资源包含证书的 CN 值映射，格式为 CN=role 或 CN=role1,role2 等。假设它包含三个条目： alice=user,admin,bob=user 和 jdoe=tester。
2 3 4: 使用 HTTP 安全策略要求 SecurityIdentity 必须具有 user 或 admin 角色才能授权请求。

假定假定配置，如果客户端证书的 CN 属性等于 alice 或 bob，则请求会被授权，如果它等于 jdoe，则请求会被禁止。

2.2.3.2. 使用证书属性增强 SecurityIdentity
复制链接

如果自动映射证书属性到 roles 选项不适合，则始终可以注册 SecurityIdentityAugmentor。自定义 SecurityIdentityAugmentor 可以检查不同客户端证书属性的值，并相应地增强 SecurityIdentity。

有关自定义 SecurityIdentity 的更多信息，请参阅 Quarkus " 安全提示和技巧"指南中的安全身份自定义部分。

2.2. 内置身份验证机制

2.2.1. 基本身份验证（Basic authentication）
复制链接

2.2.2. 基于表单的身份验证
复制链接

2.2.3. 双向 TLS 身份验证
复制链接

2.2.3.1. 将证书属性映射到角色
复制链接

2.2.3.2. 使用证书属性增强 SecurityIdentity
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.2. 内置身份验证机制

2.2.1. 基本身份验证（Basic authentication）复制链接链接已复制到粘贴板!

2.2.2. 基于表单的身份验证复制链接链接已复制到粘贴板!

2.2.3. 双向 TLS 身份验证复制链接链接已复制到粘贴板!

2.2.3.1. 将证书属性映射到角色复制链接链接已复制到粘贴板!

2.2.3.2. 使用证书属性增强 SecurityIdentity复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.2.1. 基本身份验证（Basic authentication）
复制链接

2.2.2. 基于表单的身份验证
复制链接

2.2.3. 双向 TLS 身份验证
复制链接

2.2.3.1. 将证书属性映射到角色
复制链接

2.2.3.2. 使用证书属性增强 SecurityIdentity
复制链接