Module io.quarkus.security.api
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 Details

    • AUTODETECTED

      static final String AUTODETECTED
      Constant value for params() indicating that the constructor parameters of the permission() should be autodetected based on formal parameter names. For example, consider following method secured with this annotation: 
       
 @PermissionsAllowed(value = "resource:retrieve", permission = UserPermission.class)
 public Resource getResource(String param1, String param2, String param3) {
      // business logic
 }
      The getResource method parameters param1 and param3 will be matched with the UserPermission constructor parameters param1 and param3. 
       
 public class UserPermission extends Permission {

     public UserPermission(String name, String param3, String param1) {
         ...
     }

     ...
 }
 
 If no method parameter name matches the constructor parameter name, Quarkus checks names of fields and methods
 declared on the method parameter type.
 For example:
 
       
 record BeanParam2(String param1, String param2) {}
 record BeanParam3(String param3) {}
 record BeanParam1(BeanParam2 beanParam2, BeanParam3 beanParam3) {

 }

 @PermissionsAllowed(value = "resource:retrieve", permission = UserPermission.class)
 public Resource getResource(BeanParam1 beanParam) {
      // business logic
 }

 
 }
 
      
 In this example, resolution of the param1 and param3 formal parameters is unambiguous.
 For more complex scenarios, we suggest to specify params() explicitly.
      See Also:

    • 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");
      See Also:

  • Element Details

    • 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:

    • 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.

      Method parameter fields or methods can be passed to a Permission constructor as well. Consider the following secured method and its parameters: 
       
 @PermissionsAllowed(permission = UserPermission.class, value = "resource", params = {"admin1.param1", "user1.param3"})
 public Resource getResource(User user, User user1, Admin admin, Admin admin1) {
     // business logic
 }
 class ResourceIdentity {
     private final String param1;

     public String getParam1() {
         return param1;
     }
 }
 class User extends ResourceIdentity {
     public String getParam3() {
         return "param3";
     }
 }
 class Admin extends ResourceIdentity { }
      The corresponding UserPermission constructor would look like this: 
       public class UserPermission extends Permission {

     public UserPermission(String name, String param1, String param3) {
     }

     ...
 }
      Here, the constructor parameter param1 refers to the admin1#param1 secured method parameter and the constructor parameter param3 to the user1#getParam3 secured method parameter.
      Returns:
      constructor parameters passed to the permission()
      See Also:
      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