Package io.quarkus.security

Annotation Type PermissionsAllowed

  • @Documented
@Retention(RUNTIME)
@Target({TYPE,METHOD})
@Repeatable(List.class)
public @interface PermissionsAllowed
    Indicates that a resource can only be accessed by a user with one of permissions specified through value(). There are some situations where you want to require more than one permission, this can be achieved by repeating annotation. Please see an example below: 
     @PermissionsAllowed("create")
 @PermissionsAllowed("update")
 public Resource createOrUpdate(Long id) {
     // business logic
 }
    To put it another way, permissions specified by one annotation instance are disjunctive and the permission check is only true if all annotation instances are evaluated as true.

    • Field Detail

      • AUTODETECTED

        static final String AUTODETECTED
        Constant value for params() indicating that the constructor parameters of the permission() should be autodetected. That is, each constructor argument data type must exactly match a data type of at least one argument of the secured method. For example consider following permission: 
         public class UserPermission extends Permission {

     private final User user;

     public UserPermission(String name, User user) {
         super(name);
         this.user = user;
     }

     ...
 }
        Constructor parameter user is in fact object passed to a secured method. In the example below, user1 parameter of the 'getResource' method is passed to the constructor. 
         @PermissionsAllowed(permission = UserPermission.class, value = "resource")
 public Resource getResource(User user1) {
     // business logic
 }
        Constructor parameters are always selected as the first secured method parameter with exactly matching data type. There is no limit to a reasonable number of parameters passed to the permission constructor this way. Please see params() for more complex matching.

      • PERMISSION_TO_ACTION_SEPARATOR

        static final String PERMISSION_TO_ACTION_SEPARATOR
        Colon is used to separate a Permission.getName() and an element of the Permission.getActions(). For example, StringPermission created for method 'getResource': 
         @PermissionsAllowed("resource:retrieve")
 public Resource getResource() {
     // business logic
 }
        is equal to the perm: 
         var perm = new StringPermission("resource", "retrieve");

    • Element Detail

      • value

        String[] value
        Specifies a list of permissions that grants the access to the resource. It is also possible to define permission's actions that are permitted for the resource. Yet again, consider method 'getResource': 
         @PermissionsAllowed({"resource:crud", "resource:retrieve", "system-resource:retrieve"})
 public Resource getResource() {
     // business logic
 }
        Two StringPermissions will be created: 
         var pem1 = new StringPermission("resource", "crud", "retrieve");
 var pem2 = new StringPermission("system-resource", "retrieve");
        And the permission check will pass if either pem1 or pem2 implies user permissions. Technically, it is also possible to both define actions and no action for same-named permission like this: 
         @PermissionsAllowed({"resource:crud", "resource:retrieve", "natural-resource"})
 public Resource getResource() {
     // business logic
 }
        Quarkus will create two permissions: 
         var pem1 = new StringPermission("resource", "crud", "retrieve");
 var pem2 = new StringPermission("natural-resource");
        To see how the example above is evaluated, please see "implies" method of your permission().
        Returns:
        permissions linked to respective actions
        See Also:
        for more details on how above-mentioned example is evaluated

      • inclusive

        boolean inclusive
        Choose a relation between permissions specified via value(). By default, at least one of permissions is required (please see the example above). You can require all of them by setting `inclusive` to `true`. Let's re-use same example and make permissions inclusive: 
         @PermissionsAllowed(value = {"resource:crud", "resource:retrieve", "natural-resource"}, inclusive = true)
 public Resource getResource() {
     // business logic
 }
        Two StringPermissions will be created: 
         var pem1 = new StringPermission("resource", "crud", "retrieve");
 var pem2 = new StringPermission("system-resource", "retrieve");
        And the permission check will pass if both pem1 and pem2 implies user permissions.
        Returns:
        `true` if permissions should be inclusive
        Default:
        false

      • params

        String[] params
        Mark parameters of the annotated method that should be passed to the constructor of the permission(). First, let's define ourselves three classes: 
         class ResourceIdentity { }
 class User extends ResourceIdentity { }
 class Admin extends ResourceIdentity { }
        Now that we have defined parameter data types, please consider the secured method 'getResource': 
         @PermissionsAllowed(permission = UserPermission.class, value = "resource", params = {user1, admin1})
 public Resource getResource(User user, User user1, Admin admin, Admin admin1) {
     // business logic
 }
        In the example above, we marked parameters user1 and admin1 as permission() constructor arguments: 
         public class UserPermission extends Permission {

     private final ResourceIdentity user;
     private final ResourceIdentity admin;

     public UserPermission(String name, ResourceIdentity user1, ResourceIdentity admin1) {
         super(name);
         this.user = user1;
         this.admin = admin1;
     }

     ...
 }
        Please mention that:
        • constructor parameter names user1 and admin1 must exactly match respective "params",
        • "ResourceIdentity" could be used as constructor parameter data type, for "User" and "Admin" are assignable from "ResourceIdentity",
        • "getResource" parameters user and admin are not passed to the "UserPermission" constructor.
        When this annotation is used as the class-level annotation, same requirements are put on every single secured method.

        WARNING: "params" attribute is only supported in the scenarios explicitly named in the Quarkus documentation.

        Returns:
        constructor parameters passed to the permission()
        See Also:
        AUTODETECTED
        Default:
        {"<<autodetected>>"}

      • permission

        Class<? extends Permission> permission
        The class that extends the Permission class, used to create permissions specified via value(). For example: 
         public class UserPermission extends Permission {

     private final String[] permissions;

     public UserPermission(String name, String... actions) {
         super(name);
         this.actions = actions;
     }

     ...
 }
        actions parameter is optional and may be omitted.
        Returns:
        permission class
        Default:
        io.quarkus.security.StringPermission.class