1.2. 使用注解的授权
红帽构建的 Quarkus 包含内置的安全性,允许基于通用安全注解 @RolesAllowed、@DenyAll、@PermitAll on REST 端点和 CDI Bean 进行 基于角色的访问控制(RBAC)。
| 注解类型 | 描述 |
|---|---|
|
| 指定不允许安全角色调用指定方法。 |
|
| 指定允许所有安全角色调用指定方法。
|
|
| 指定允许访问应用中的方法的安全角色列表。
作为等同于 |
以下 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")
public String getSubjectSecured(@Context SecurityContext sec) {
Principal user = sec.getUserPrincipal();
String name = user != null ? user.getName() : "anonymous";
return name;
}
@GET
@Path("unsecured")
@PermitAll
public String getSubjectUnsecured(@Context SecurityContext sec) {
Principal user = sec.getUserPrincipal();
String name = user != null ? user.getName() : "anonymous";
return name;
}
@GET
@Path("denied")
@DenyAll
public String getSubjectDenied(@Context SecurityContext sec) {
Principal user = sec.getUserPrincipal();
String name = user != null ? user.getName() : "anonymous";
return name;
}
}
- 1
/subject/secured端点需要一个经过身份验证的用户,并通过使用@RolesAllowed ("Tester")注解来赋予"Tester"角色。- 2
- 端点从 Jakarta REST
SecurityContext获取用户主体。这会为安全端点返回非null。 - 3
/subject/unsecured端点通过指定@PermitAll注释来允许未经身份验证的访问。- 4
- 如果调用者通过身份验证,则获取用户主体的调用会返回
null,如果调用者是未经身份验证的且非null。 - 5
/subject/denied端点声明@DenyAll注释,不允许所有直接访问它作为 REST 方法,无论用户调用它。这个方法仍然可以通过此类中的其他方法在内部调用。
如果您计划在 IO 线程上使用标准安全注解,请查看 主动身份验证 中的信息。
@RolesAllowed 注释值支持属性 表达式,包括默认值和嵌套属性表达式。与注解搭配使用的配置属性在运行时解析。
| 注解 | 值解释 |
|---|---|
|
|
端点允许用户具有由 |
|
| 显示值可以包含多个变量的示例。 |
|
|
默认值演示。所需的角色由 |
@RolesAllowed 注释中的属性表达式用法示例
admin=Administrator
tester.group=Software
tester.role=Tester
%prod.secured=User
%dev.secured=**
all-roles=Administrator,Software,Tester,User
主题访问控制示例
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}")
public String getSubjectSecuredAdmin(@Context SecurityContext sec) {
return getUsername(sec);
}
@GET
@Path("software-tester")
@RolesAllowed("${tester.group}-${tester.role}")
public String getSubjectSoftwareTester(@Context SecurityContext sec) {
return getUsername(sec);
}
@GET
@Path("user")
@RolesAllowed("${customer:User}")
public String getSubjectUser(@Context SecurityContext sec) {
return getUsername(sec);
}
@GET
@Path("secured")
@RolesAllowed("${secured}")
public String getSubjectSecured(@Context SecurityContext sec) {
return getUsername(sec);
}
@GET
@Path("list")
@RolesAllowed("${all-roles}")
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;
}
}
- 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")
@PermissionsAllowed("update")
@POST
@Path("/modify/repeated")
public String createOrUpdate() {
return "modified";
}
@PermissionsAllowed(value = {"create", "update"}, inclusive=true)
@POST
@Path("/modify/inclusive")
public String createOrUpdate(Long id) {
return id + " modified";
}
@PermissionsAllowed({"see:detail", "see:all", "read"})
@GET
@Path("/id/{id}")
public String getItem(String id) {
return "item-detail-" + id;
}
@PermissionsAllowed(value = "list", permission = CustomPermission.class)
@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();
var publicContent = "public-content".equals(event.request().params().get("query-options"));
var hasPermission = getName().equals(permission.getName());
return hasPermission && publicContent;
}
}
}
- 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 实例。
如果您计划在 IO 线程上使用 @PermissionsAllowed,请查看 主动身份验证 中的信息。
由于 Quarkus 拦截器的限制,在类级别上不可重复 @PermissionsAllowed。如需更多信息,请参阅 Quarkus "CDI 参考" 指南中的 Repeatable interceptor bindings 部分。
将权限添加到启用了角色的 SecurityIdentity 实例的最简单方法是将角色映射到权限。使用带有配置的 Authorization 将 CRUDResource 端点所需的 SecurityIdentity 权限授予经过身份验证的用户,如下例所示:
quarkus.http.auth.policy.role-policy1.permissions.user=see:all
quarkus.http.auth.policy.role-policy1.permissions.admin=create,update,read
quarkus.http.auth.permission.roles1.paths=/crud/modify/*,/crud/id/*
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
quarkus.http.auth.permission.roles2.paths=/crud/list
quarkus.http.auth.permission.roles2.policy=role-policy2
- 1
- 将权限
see和操作添加到用户角色的SecurityIdentity实例。同样,对于@PermissionsAllowed注释,默认为使用io.quarkus.security.StringPermission。 - 2
- 权限
创建、update和read映射到角色admin。 - 3
- 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) {
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
}
}
- 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)
public Library updateLibrary(String newDesc, Library update) {
update.description = newDesc;
return update;
}
@PermissionsAllowed(value = "tv:write", permission = LibraryPermission.class, params = "library")
@PermissionsAllowed(value = {"tv:read", "tv:list"}, permission = LibraryPermission.class)
public Library migrateLibrary(Library migrate, Library library) {
// migrate libraries
return library;
}
}
使用 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);
}
}
与 CRUDResource 示例类似,以下示例演示了如何授予用户具有 admin 角色权限的用户来更新 MediaLibrary :
package org.acme.library;
import io.quarkus.runtime.annotations.RegisterForReflection;
@RegisterForReflection
public class MediaLibraryPermission extends LibraryPermission {
public MediaLibraryPermission(String libraryName, String[] actions) {
super(libraryName, actions, new MediaLibrary());
}
}
quarkus.http.auth.policy.role-policy3.permissions.admin=media-library:list,media-library:read,media-library:write
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
- 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"});
return QuarkusSecurityIdentity.builder(identity)
.addPermissionChecker(new Function<Permission, Uni<Boolean>>() {
@Override
public Uni<Boolean> apply(Permission requiredPermission) {
boolean accessGranted = possessedPermission.implies(requiredPermission);
return Uni.createFrom().item(accessGranted);
}
})
.build();
}
}
基于注解的权限无法用于自定义 Jakarta REST SecurityContexts,因为 jakarta.ws.rs.core.SecurityContext 中没有权限。