Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 1 章 Web 端点授权

Quarkus 融合了一个可插拔的 Web 安全层。当安全性处于活动状态时，系统会对所有 HTTP 请求执行权限检查，以确定它们是否应该继续。

如果路径受 quarkus.http.auth. 配置限制，则使用 @PermitAll 将不会打开路径。为确保可以访问特定的路径，必须在 Quarkus 安全设置中进行适当的配置。

注意

如果使用 Jakarta RESTful Web 服务，请考虑使用 quarkus.security.jaxrs.deny-unannotated-endpoints 或 quarkus.security.jaxrs.default-roles-allowed 来设置默认安全要求，而不是 HTTP 路径级别匹配，因为注解可以在单个端点上覆盖这些属性。

授权基于安全提供程序提供的用户角色。要自定义这些角色，可以创建一个 SecurityIdentityAugmentor，请参阅 安全身份自定义。

1.1. 使用配置授权
复制链接

权限通过权限集在 Quarkus 配置中定义，每个都指定了访问控制的策略。

Expand
表 1.1. Red Hat build of Quarkus 策略概述
内置策略描述

deny

此策略拒绝所有用户。

permit

此策略允许所有用户。

已验证

此策略仅允许经过身份验证的用户。

您可以定义基于角色的策略，以允许具有特定角色的用户访问资源。

基于角色的策略示例

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

1
这将定义一个基于角色的策略，允许用户使用 用户和 admin 角色。

您可以通过配置 application.properties 文件中定义的内置权限集来引用自定义策略，如以下配置示例所示：

策略配置示例

quarkus.http.auth.permission.permit1.paths=/public/*
1 

quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET

quarkus.http.auth.permission.deny1.paths=/forbidden
2 

quarkus.http.auth.permission.deny1.policy=deny

quarkus.http.auth.permission.roles1.paths=/roles-secured/*,/other/*,/api/*
3 

quarkus.http.auth.permission.roles1.policy=role-policy1

1
此权限引用了默认的内置 允许 策略，以允许 GET 方法访问 /public。在这种情况下，演示的设置不会影响这个示例，因为允许此请求。
2
此权限引用 /forbidden 的内置 deny 策略。它是精确的路径匹配，因为它不以 * 结尾。
3
此权限集引用之前定义的策略。roles1 是一个示例名称，您可以调用您想要的权限集。
警告

示例中的确切路径 /forbidden 将不会保护 /forbidden/ 路径。为 /forbidden/ 路径添加新的准确路径，以确保适当的安全覆盖。

1.1.1. 自定义 HttpSecurityPolicy
复制链接

有时，注册您自己的命名策略可能很有用。您可以通过创建实现 io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy 接口的应用程序范围 CDI bean 来实现它，如下例所示： 

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy;
import io.smallrye.mutiny.Uni;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomNamedHttpSecPolicy implements HttpSecurityPolicy {
    @Override
    public Uni<CheckResult> checkPermission(RoutingContext event, Uni<SecurityIdentity> identity,
            AuthorizationRequestContext requestContext) {
        if (customRequestAuthorization(event)) {
            return Uni.createFrom().item(CheckResult.PERMIT);
        }
        return Uni.createFrom().item(CheckResult.DENY);
    }

    @Override
    public String name() {
        return "custom";
1 

    }

    private static boolean customRequestAuthorization(RoutingContext event) {
        // here comes your own security check
        return !event.request().path().endsWith("denied");
    }
}
1
命名 HTTP 安全策略将仅应用于与 application.properties 路径匹配规则匹配的请求。

从配置文件引用的名为 HttpSecurityPolicy 的自定义示例

quarkus.http.auth.permission.custom1.paths=/custom/*
quarkus.http.auth.permission.custom1.policy=custom
1

1
自定义策略名称必须与 io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy.name 方法返回的值匹配。
提示

您还可以在每个请求上创建全局 HttpSecurityPolicy 调用。只需实施 io.quarkus.vertx.http.runtime.security.HttpSecurityPolicy.name 方法，并将策略名称留空。

1.1.2. 匹配路径和方法
复制链接

权限集也可以将路径和方法指定为用逗号分开的列表。如果路径以 * 通配符结尾，则查询会生成与所有子路径匹配。否则，它会查询完全匹配，且只与该特定路径匹配： 

quarkus.http.auth.permission.permit1.paths=/public*,/css/*,/js/*,/robots.txt
1 

quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD
1
路径末尾的 * 通配符匹配零个或多个路径片段，但从 /public 路径开始的任何词语。因此，/public-info 等路径与此模式不匹配。

1.1.3. 匹配路径而不是方法
复制链接

如果请求根据路径匹配一个或多个权限集，但不需要的方法，则请求将被拒绝。

提示

根据前面的权限集，GET /public/foo 将匹配路径和方法，因此被允许。相反，POST /public/foo 将匹配路径，而不是方法，因此被拒绝。

1.1.4. 匹配多个路径：路径的最成功
复制链接

匹配始终以"最长路径优先"为基础完成。如果一个更具体的权限集匹配，则不会被考虑： 

quarkus.http.auth.permission.permit1.paths=/public/*
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD

quarkus.http.auth.permission.deny1.paths=/public/forbidden-folder/*
quarkus.http.auth.permission.deny1.policy=deny
提示

根据前面的权限集，GET /public/forbidden-folder/foo 将同时匹配这两个权限集的路径。但是，由于较长的路径与 deny1 权限集的路径匹配，因此选择了 deny1，请求将被拒绝。

注意

subPath 权限之前带有 root 路径权限，因为 deny1 和 permit1 权限示例之前演示了。

此规则通过一个场景进一步说明，其中 subpath 权限允许访问公共资源，而 root 路径权限需要授权。 

quarkus.http.auth.policy.user-policy.roles-allowed=user
quarkus.http.auth.permission.roles.paths=/api/*
quarkus.http.auth.permission.roles.policy=user-policy

quarkus.http.auth.permission.public.paths=/api/noauth/*
quarkus.http.auth.permission.public.policy=permit

在以前的版本中，当一个路径使用 * 通配符结束时，会演示与所有子路径匹配的示例。

此通配符也适用于代表单一路径段的路径中。它不能与其他路径段字符混合；因此，路径分隔符始终将 * 通配符括起，如 /public/*/about-us 路径中所示。

当多个路径模式与同一请求路径对应时，系统会选择最长的子路径，从而导致 * 通配符。在这种情况下，每个路径片段字符都比 * 通配符更具体。

以下是一个简单的示例： 

quarkus.http.auth.permission.secured.paths=/api/*/detail
1 

quarkus.http.auth.permission.secured.policy=authenticated
quarkus.http.auth.permission.public.paths=/api/public-product/detail
2 

quarkus.http.auth.permission.public.policy=permit
1
请求路径（如 /api/product/detail ）只能被经过身份验证的用户访问。
2
路径 /api/public-product/detail 更为具体，因此任何人都可以访问。
重要

应该测试使用配置通过授权保护的所有路径。使用多个通配符编写路径模式可能很繁琐。请确保路径已如预期授权。

在以下示例中，路径从最特定于最具体的路径排序：

请求路径 /one/two/three/four/five 匹配从最特定于最具体的路径排序

/one/two/three/four/five
/one/two/three/four/*
/one/two/three/*/five
/one/two/three/*/*
/one/two/*/four/five
/one/*/three/four/five
/*/two/three/four/five
/*/two/three/*/five
/*

重要

路径末尾的 * 通配符与零个或多个路径片段匹配。* 通配符放置在其它任何位置与一个路径片段匹配。

1.1.6. 匹配多个路径：最具体的方法胜出
复制链接

当使用多个权限集注册路径时，权限集会明确指定与请求匹配的 HTTP 方法。在本实例中，只有请求方法与方法规格不匹配时，没有方法的权限集才会生效。 

quarkus.http.auth.permission.permit1.paths=/public/*
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD

quarkus.http.auth.permission.deny1.paths=/public/*
quarkus.http.auth.permission.deny1.policy=deny
注意

前面的权限集显示 GET /public/foo 与这两个权限集的路径匹配。如何，它特别符合 permit1 权限集的显式方法。选择 permit1，并接受请求。

相反，PUT /public/foo 与 allow 1 的方法不匹配。因此，会激活 deny1，从而导致请求拒绝。

1.1.7. 匹配多个路径和方法：它们都成功
复制链接

有时，前面描述的规则允许同时有多个权限集 win。在这种情况下，要进行请求，所有权限都必须允许访问。要实现此目的，两者都必须指定方法或没有方法。特定于方法的匹配优先。 

quarkus.http.auth.policy.user-policy1.roles-allowed=user
quarkus.http.auth.policy.admin-policy1.roles-allowed=admin

quarkus.http.auth.permission.roles1.paths=/api/*,/restricted/*
quarkus.http.auth.permission.roles1.policy=user-policy1

quarkus.http.auth.permission.roles2.paths=/api/*,/admin/*
quarkus.http.auth.permission.roles2.policy=admin-policy1
提示

根据前面的权限集，GET /api/foo 将匹配权限集的路径，这需要 用户和 admin 角色。

1.1.8. 拒绝访问的配置属性
复制链接

以下配置设置更改基于角色的访问控制(RBAC)拒绝行为：

quarkus.security.jaxrs.deny-unannotated-endpoints=true|false
如果设置为 true，则默认拒绝所有 Jakarta REST 端点的访问。如果 Jakarta REST 端点没有安全注解，则默认为 @DenyAll 行为。这有助于避免意外公开应该被保护的端点。默认值为 false。
quarkus.security.jaxrs.default-roles-allowed=role1,role2
定义未注解端点的默认角色要求。** 角色是一个特殊的角色，代表任何经过身份验证的用户。这不能与 deny-unannotated-endpoints 结合使用，因为 deny 会生效。
quarkus.security.deny-unannotated-members=true|false
如果设置为 true，则拒绝访问所有 CDI 方法和没有安全注解的 Jakarta REST 端点，但在包含安全注解方法的类中定义。默认值为 false。

1.1.9. 禁用权限
复制链接

构建时可以禁用权限，每个声明的权限 都启用了 属性，例如： 

quarkus.http.auth.permission.permit1.enabled=false
quarkus.http.auth.permission.permit1.paths=/public/*,/css/*,/js/*,/robots.txt
quarkus.http.auth.permission.permit1.policy=permit
quarkus.http.auth.permission.permit1.methods=GET,HEAD

使用系统属性或环境变量在运行时可以重新启用权限，例如： -Dquarkus.http.auth.permission.permit1.enabled=true。

1.1.10. 权限路径和 HTTP 根路径
复制链接

quarkus.http.root-path 配置属性更改 http 端点上下文路径。

默认情况下，quarkus.http.root-path 会自动添加到配置的权限路径前，然后不要使用正斜杠，例如： 

quarkus.http.auth.permission.permit1.paths=public/*,css/*,js/*,robots.txt

此配置等同于以下内容： 

quarkus.http.auth.permission.permit1.paths=${quarkus.http.root-path}/public/*,${quarkus.http.root-path}/css/*,${quarkus.http.root-path}/js/*,${quarkus.http.root-path}/robots.txt

前面斜杠会改变配置的权限路径的解释方式。配置的 URL 用于按原样使用，如果 quarkus.http.root-path 的值发生了变化，则不会调整路径。

Example:

quarkus.http.auth.permission.permit1.paths=/public/*,css/*,js/*,robots.txt

此配置仅影响从固定或静态 URL 提供的资源 /public，如果 quarkus.http.root-path 已设置为 / 以外的其他路径，则这可能与您的应用程序资源不匹配。

如需更多信息，请参阅 Quarkus 中的路径解析。

1.1.11. 映射 SecurityIdentity 角色
复制链接

获奖基于角色的策略可以将 SecurityIdentity 角色映射到特定于部署的角色。然后，这些角色适用于使用 @RolesAllowed 注释的端点授权。 

quarkus.http.auth.policy.admin-policy1.roles.admin=Admin1
1 

quarkus.http.auth.permission.roles1.paths=/*
quarkus.http.auth.permission.roles1.policy=admin-policy1
1
将 admin 角色映射到 Admin1 角色。SecurityIdentity 将同时具有 admin 和 Admin1 角色。

1.1.12. 共享权限检查
复制链接

用于未共享权限检查的一个重要规则是仅应用一个路径匹配，它是最具体的。自然，您可以使用与您想要相同的获奖路径来指定多个权限，并全部应用它们。但是，有可能有权限检查，您希望应用到许多路径，而无需重复它们，然后再次重复它们。这是共享权限检查所在的位置，当权限路径匹配时，它们总是被应用。

每个 HTTP 请求中应用名为 HttpSecurityPolicy 的自定义示例

quarkus.http.auth.permission.custom1.paths=/*
quarkus.http.auth.permission.custom1.shared=true
1 

quarkus.http.auth.permission.custom1.policy=custom

quarkus.http.auth.policy.admin-policy1.roles-allowed=admin
quarkus.http.auth.permission.roles1.paths=/admin/*
quarkus.http.auth.permission.roles1.policy=admin-policy1

1
自定义 HttpSecurityPolicy 也会与 admin-policy1 策略一起应用到 /admin/1 路径。
提示

配置许多共享权限检查比配置不共享权限检查更有效。使用共享权限补充下例中的未共享权限检查。

使用共享权限映射 SecurityIdentity 角色

quarkus.http.auth.policy.role-policy1.roles.root=admin,user
1 

quarkus.http.auth.permission.roles1.paths=/secured/*
2 

quarkus.http.auth.permission.roles1.policy=role-policy1
quarkus.http.auth.permission.roles1.shared=true

quarkus.http.auth.policy.role-policy2.roles-allowed=user
3 

quarkus.http.auth.permission.roles2.paths=/secured/user/*
quarkus.http.auth.permission.roles2.policy=role-policy2

quarkus.http.auth.policy.role-policy3.roles-allowed=admin
quarkus.http.auth.permission.roles3.paths=/secured/admin/*
quarkus.http.auth.permission.roles3.policy=role-policy3

1
角色 root 可以访问 /secured/user8:0:1:: 和 /secured/admin prerequisites 路径。
2
/secured Attr 路径只能被经过身份验证的用户访问。这样，您已保护了 /secured/all 路径，以此类推。
3
共享权限始终会在不共享前应用，因此具有 root 角色的 SecurityIdentity 也具有用户角色。
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

Legal Notice

Theme

© 2026 Red Hat返回顶部