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

1.2. 使用注解的授权

红帽构建的 Quarkus 包含内置的安全性，允许基于通用安全注解 @RolesAllowed、@DenyAll、@PermitAll on REST 端点和 CDI Bean 进行 基于角色的访问控制(RBAC)。

Expand
表 1.2. Red Hat build of Quarkus 注解类型概述
注解类型描述

@DenyAll

指定不允许安全角色调用指定方法。

@PermitAll

指定允许所有安全角色调用指定方法。

@PermitAll 允许其中的任何人，即使没有身份验证。

@RolesAllowed

指定允许访问应用中的方法的安全角色列表。

作为等同于 @RolesAllowed ("**")，红帽构建的 Quarkus 还提供 io.quarkus.security.Authenticated 注解，允许任何经过身份验证的用户访问该资源。

以下 SubjectExposingResource 示例演示了 一个端点，它使用 Jakarta REST 和 Common Security 注解来描述和保护其端点。

SubjectExposingResource 示例

import java.security.Principal;

import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.SecurityContext;

@Path("subject")
public class SubjectExposingResource {

    @GET
    @Path("secured")
    @RolesAllowed("Tester")
1 

    public String getSubjectSecured(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal();
2 

        String name = user != null ? user.getName() : "anonymous";
        return name;
    }

    @GET
    @Path("unsecured")
    @PermitAll
3 

    public String getSubjectUnsecured(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal();
4 

        String name = user != null ? user.getName() : "anonymous";
        return name;
    }

    @GET
    @Path("denied")
    @DenyAll
5 

    public String getSubjectDenied(@Context SecurityContext sec) {
        Principal user = sec.getUserPrincipal();
        String name = user != null ? user.getName() : "anonymous";
        return name;
    }
}
Copy to Clipboard Toggle word wrap

1
/subject/secured 端点需要一个经过身份验证的用户，并通过使用 @RolesAllowed ("Tester") 注解来赋予"Tester"角色。
2
端点从 Jakarta REST SecurityContext 获取用户主体。这会为安全端点返回 非null。
3
/subject/unsecured 端点通过指定 @PermitAll 注释来允许未经身份验证的访问。
4
如果调用者通过身份验证，则获取用户主体的调用会返回 null，如果调用者是未经身份验证的且 非null。
5
/subject/denied 端点声明 @DenyAll 注释，不允许所有直接访问它作为 REST 方法，无论用户调用它。这个方法仍然可以通过此类中的其他方法在内部调用。
Important

如果您计划在 IO 线程上使用标准安全注解，请查看 主动身份验证 中的信息。

@RolesAllowed 注释值支持属性 表达式，包括默认值和嵌套属性表达式。与注解搭配使用的配置属性在运行时解析。

Expand
表 1.3. 注解值示例
注解值解释

@RolesAllowed("${admin-role}")

端点允许用户具有由 admin-role 属性的值表示的角色。

@RolesAllowed("${tester.group}-${tester.role}")

显示值可以包含多个变量的示例。

@RolesAllowed("${customer:User}")

默认值演示。所需的角色由 customer 属性的值表示。但是，如果没有指定该属性，则需要名为 User 的角色作为默认值。

@RolesAllowed 注释中的属性表达式用法示例

admin=Administrator
tester.group=Software
tester.role=Tester
%prod.secured=User
%dev.secured=**
all-roles=Administrator,Software,Tester,User
Copy to Clipboard Toggle word wrap

主题访问控制示例

import java.security.Principal;

import jakarta.annotation.security.DenyAll;
import jakarta.annotation.security.PermitAll;
import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.SecurityContext;

@Path("subject")
public class SubjectExposingResource {

    @GET
    @Path("admin")
    @RolesAllowed("${admin}")
1 

    public String getSubjectSecuredAdmin(@Context SecurityContext sec) {
        return getUsername(sec);
    }

    @GET
    @Path("software-tester")
    @RolesAllowed("${tester.group}-${tester.role}")
2 

    public String getSubjectSoftwareTester(@Context SecurityContext sec) {
        return getUsername(sec);
    }

    @GET
    @Path("user")
    @RolesAllowed("${customer:User}")
3 

    public String getSubjectUser(@Context SecurityContext sec) {
        return getUsername(sec);
    }

    @GET
    @Path("secured")
    @RolesAllowed("${secured}")
4 

    public String getSubjectSecured(@Context SecurityContext sec) {
        return getUsername(sec);
    }

    @GET
    @Path("list")
    @RolesAllowed("${all-roles}")
5 

    public String getSubjectList(@Context SecurityContext sec) {
        return getUsername(sec);
    }

    private String getUsername(SecurityContext sec) {
        Principal user = sec.getUserPrincipal();
        String name = user != null ? user.getName() : "anonymous";
        return name;
    }
}
Copy to Clipboard Toggle word wrap

1
@RolesAllowed 注释值设为 Administrator 的值。
2
这个 /subject/software-tester 端点需要一个经过身份验证的用户，它被授予了 "Software-Tester" 角色。可以在角色定义中使用多个表达式。
3
此 /subject/user 端点需要一个经过身份验证的用户，它已通过使用 @RolesAllowed ("${customer:User}") 注解授予角色"User"，因为我们没有设置配置属性 客户。
4
在生产环境中，这个 /subject/secured 端点需要一个具有 User 角色的经过身份验证的用户。在开发模式中，它允许任何经过身份验证的用户。
5
属性表达式 all-roles 将被视为集合类型列表，因此角色 管理员、软件、测试 程序和用户可以访问端点。

1.2.1. 权限注解
复制链接

Quarkus 还提供 io.quarkus.security.PermissionsAllowed 注解，它授权具有给定权限访问资源的任何经过身份验证的用户。此注解是通用安全注解的扩展，并检查授予 SecurityIdentity 实例的权限。

使用 @PermissionsAllowed 注释保护的端点示例

package org.acme.crud;

import io.quarkus.arc.Arc;
import io.vertx.ext.web.RoutingContext;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.QueryParam;

import io.quarkus.security.PermissionsAllowed;

import java.security.BasicPermission;
import java.security.Permission;
import java.util.Collection;
import java.util.Collections;

@Path("/crud")
public class CRUDResource {

    @PermissionsAllowed("create")
1 

    @PermissionsAllowed("update")
    @POST
    @Path("/modify/repeated")
    public String createOrUpdate() {
        return "modified";
    }

    @PermissionsAllowed(value = {"create", "update"}, inclusive=true)
2 

    @POST
    @Path("/modify/inclusive")
    public String createOrUpdate(Long id) {
        return id + " modified";
    }

    @PermissionsAllowed({"see:detail", "see:all", "read"})
3 

    @GET
    @Path("/id/{id}")
    public String getItem(String id) {
        return "item-detail-" + id;
    }

    @PermissionsAllowed(value = "list", permission = CustomPermission.class)
4 

    @Path("/list")
    @GET
    public Collection<String> list(@QueryParam("query-options") String queryOptions) {
        // your business logic comes here
        return Collections.emptySet();
    }

    public static class CustomPermission extends BasicPermission {

        public CustomPermission(String name) {
            super(name);
        }

        @Override
        public boolean implies(Permission permission) {
            var event = Arc.container().instance(RoutingContext.class).get();
5 

            var publicContent = "public-content".equals(event.request().params().get("query-options"));
            var hasPermission = getName().equals(permission.getName());
            return hasPermission && publicContent;
        }
    }
}
Copy to Clipboard Toggle word wrap

1
资源方法 createOrUpdate 只能供具有 create 和 update 权限的用户访问。
2
默认情况下，至少需要一个注解实例指定的权限之一。您可以通过设置 inclusive=true 来要求所有权限。这两种资源方法都 createOrUpdate 具有相同的授权要求。
3
如果 SecurityIdentity 具有读取权限 或查看 权限以及 all 或 detail 操作之一，则访问权限会被授予 getItem。
4
您可以使用您首选的 java.security.Permission 实现。默认情况下，基于字符串的权限由 io.quarkus.security.StringPermission 执行。
5
权限不是 Bean，因此使用 Arc.container （） 以编程方式获取 bean 实例。
Important

如果您计划在 IO 线程上使用 @PermissionsAllowed，请查看 主动身份验证 中的信息。

注意

由于 Quarkus 拦截器的限制，在类级别上不可重复 @PermissionsAllowed。如需更多信息，请参阅 Quarkus "CDI 参考" 指南中的 Repeatable interceptor bindings 部分。

将权限添加到启用了角色的 SecurityIdentity 实例的最简单方法是将角色映射到权限。使用带有配置的 Authorization 将 CRUDResource 端点所需的 SecurityIdentity 权限授予经过身份验证的用户，如下例所示： 

quarkus.http.auth.policy.role-policy1.permissions.user=see:all
1 

quarkus.http.auth.policy.role-policy1.permissions.admin=create,update,read
2 

quarkus.http.auth.permission.roles1.paths=/crud/modify/*,/crud/id/*
3 

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

quarkus.http.auth.policy.role-policy2.permissions.user=list
quarkus.http.auth.policy.role-policy2.permission-class=org.acme.crud.CRUDResource$CustomPermission
4 

quarkus.http.auth.permission.roles2.paths=/crud/list
quarkus.http.auth.permission.roles2.policy=role-policy2
Copy to Clipboard Toggle word wrap
1
将权限 see 和 操作 添加到 用户角色的 SecurityIdentity 实例。同样，对于 @PermissionsAllowed 注释，默认为使用 io.quarkus.security.StringPermission。
2
权限 创建、update 和 read 映射到角色 admin。
3
角色策略 role-policy1 只允许经过身份验证的用户访问 /crud/modify 和 /crud/id 子路径。有关路径匹配算法的更多信息，请参阅本指南稍后 匹配多个路径：最长路径优先。
4
您可以指定 java.security.Permission 类的自定义实现。自定义类必须精确定义一个构造器，接受权限名称和可选的操作，如 String 数组。在这种情况下，权限列表被添加到 SecurityIdentity 实例中，作为 新的 CustomPermission (" list ")。

您还可以使用额外的构造器参数创建自定义 java.security.Permission 类。这些额外参数与通过 @PermissionsAllowed 注释注释的方法的参数匹配。之后，Quarkus 使用实际参数实例化您的自定义权限，其方法被调用 @PermissionsAllowed。

接受额外参数的自定义 java.security.Permission 类示例

package org.acme.library;

import java.security.Permission;
import java.util.Arrays;
import java.util.Set;

public class LibraryPermission extends Permission {

    private final Set<String> actions;
    private final Library library;

    public LibraryPermission(String libraryName, String[] actions, Library library) {
1 

        super(libraryName);
        this.actions = Set.copyOf(Arrays.asList(actions));
        this.library = library;
    }

    @Override
    public boolean implies(Permission requiredPermission) {
        if (requiredPermission instanceof LibraryPermission) {
            LibraryPermission that = (LibraryPermission) requiredPermission;
            boolean librariesMatch = getName().equals(that.getName());
            boolean requiredLibraryIsSublibrary = library.isParentLibraryOf(that.library);
            boolean hasOneOfRequiredActions = that.actions.stream().anyMatch(actions::contains);
            return (librariesMatch || requiredLibraryIsSublibrary) && hasOneOfRequiredActions;
        }
        return false;
    }

    // here comes your own implementation of the `java.security.Permission` class methods

    public static abstract class Library {

        protected String description;

        abstract boolean isParentLibraryOf(Library library);

    }

    public static class MediaLibrary extends Library {

        @Override
        boolean isParentLibraryOf(Library library) {
            return library instanceof MediaLibrary;
        }
    }

    public static class TvLibrary extends MediaLibrary {
        // TvLibrary specific implementation of the 'isParentLibraryOf' method
    }
}
Copy to Clipboard Toggle word wrap

1
自定义 权限 类必须正好有一个构造器。第一个参数始终被视为权限名称，且必须是 String 类型。Quarkus 可以选择性地将权限操作传给构造器。要发生这种情况，请将第二个参数声明为 String[]。

如果允许 SecurityIdentity 执行必要的操作之一，则 LibraryPermission 类允许访问当前或父库，如 读取、写入或 列表。

以下示例演示了如何使用 LibraryPermission 类： 

package org.acme.library;

import io.quarkus.security.PermissionsAllowed;
import jakarta.enterprise.context.ApplicationScoped;
import org.acme.library.LibraryPermission.Library;

@ApplicationScoped
public class LibraryService {

    @PermissionsAllowed(value = "tv:write", permission = LibraryPermission.class)
1 

    public Library updateLibrary(String newDesc, Library update) {
        update.description = newDesc;
        return update;
    }

    @PermissionsAllowed(value = "tv:write", permission = LibraryPermission.class, params = "library")
2 

    @PermissionsAllowed(value = {"tv:read", "tv:list"}, permission = LibraryPermission.class)
    public Library migrateLibrary(Library migrate, Library library) {
        // migrate libraries
        return library;
    }

}
Copy to Clipboard Toggle word wrap
1
正式参数 更新 被识别为第一个 Library 参数，并传递到 LibraryPermission 类。但是，每次调用 updateLibrary 方法时，必须实例化 LibraryPermission。
2
在这里，第一个 库 参数是 migrate，因此 library 参数通过 PermissionsAllowed#params 明确标记为。权限构造器和注解的方法必须设置参数 库 ；否则，验证失败。

使用 LibraryPermission保护的资源示例

package org.acme.library;

import io.quarkus.security.PermissionsAllowed;
import jakarta.inject.Inject;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import org.acme.library.LibraryPermission.Library;

@Path("/library")
public class LibraryResource {

    @Inject
    LibraryService libraryService;

    @PermissionsAllowed(value = "tv:write", permission = LibraryPermission.class)
    @PUT
    @Path("/id/{id}")
    public Library updateLibrary(@PathParam("id") Integer id, Library library) {
        ...
    }

    @PUT
    @Path("/service-way/id/{id}")
    public Library updateLibrarySvc(@PathParam("id") Integer id, Library library) {
        String newDescription = "new description " + id;
        return libraryService.updateLibrary(newDescription, library);
    }

}
Copy to Clipboard Toggle word wrap

与 CRUDResource 示例类似，以下示例演示了如何授予用户具有 admin 角色权限的用户来更新 MediaLibrary ： 

package org.acme.library;

import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection
1 

public class MediaLibraryPermission extends LibraryPermission {

    public MediaLibraryPermission(String libraryName, String[] actions) {
        super(libraryName, actions, new MediaLibrary());
2 

    }

}
Copy to Clipboard Toggle word wrap
1
在构建原生可执行文件时，必须注册权限类进行反映，除非它至少用于一个 io.quarkus.security.PermissionsAllowed#name 参数。
2
我们希望 MediaLibrary 实例传递到 LibraryPermission 构造器。 
quarkus.http.auth.policy.role-policy3.permissions.admin=media-library:list,media-library:read,media-library:write
1 

quarkus.http.auth.policy.role-policy3.permission-class=org.acme.library.MediaLibraryPermission
quarkus.http.auth.permission.roles3.paths=/library/*
quarkus.http.auth.permission.roles3.policy=role-policy3
Copy to Clipboard Toggle word wrap
1
授予权限 media-library，允许 读取、写 和 list 操作。由于 MediaLibrary 是 TvLibrary 类父项，因此也允许具有 admin 角色的用户修改 TvLibrary。
提示

/libraryAttr 路径可以从 Keycloak 供应商 Dev UI 页面中测试，因为用户 alice 由 Keycloak 的 Dev Services 自动创建的用户具有 admin 角色。

目前为止提供的示例演示角色到权限映射。也可以以编程方式向 SecurityIdentity 实例添加权限。在以下示例中，SecurityIdentity 被自定义，以添加之前通过基于 HTTP 基于角色的访问控制相同的权限。

以编程方式将 LibraryPermission 添加到 SecurityIdentity的示例

import java.security.Permission;
import java.util.function.Function;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.security.identity.AuthenticationRequestContext;
import io.quarkus.security.identity.SecurityIdentity;
import io.quarkus.security.identity.SecurityIdentityAugmentor;
import io.quarkus.security.runtime.QuarkusSecurityIdentity;
import io.smallrye.mutiny.Uni;

@ApplicationScoped
public class PermissionsIdentityAugmentor implements SecurityIdentityAugmentor {

    @Override
    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
        if (isNotAdmin(identity)) {
            return Uni.createFrom().item(identity);
        }
        return Uni.createFrom().item(build(identity));
    }

    private boolean isNotAdmin(SecurityIdentity identity) {
        return identity.isAnonymous() || !"admin".equals(identity.getPrincipal().getName());
    }

    SecurityIdentity build(SecurityIdentity identity) {
        Permission possessedPermission = new MediaLibraryPermission("media-library",
                new String[] { "read", "write", "list"});
1 

        return QuarkusSecurityIdentity.builder(identity)
                .addPermissionChecker(new Function<Permission, Uni<Boolean>>() {
2 

                    @Override
                    public Uni<Boolean> apply(Permission requiredPermission) {
                        boolean accessGranted = possessedPermission.implies(requiredPermission);
                        return Uni.createFrom().item(accessGranted);
                    }
                })
                .build();
    }

}
Copy to Clipboard Toggle word wrap

1
创建的权限 media-library 可以执行 读取、写入 和列出 操作。由于 MediaLibrary 是 TvLibrary 类父项，因此也允许具有 admin 角色的用户修改 TvLibrary。
2
您可以通过 io.quarkus.security.runtime.QuarkusSecurityIdentity.Builder#addPermissionChecker 添加权限检查程序。
Important

基于注解的权限无法用于自定义 Jakarta REST SecurityContexts，因为 jakarta.ws.rs.core.SecurityContext 中没有权限。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat