Module io.quarkus.security.api
Package io.quarkus.security

Annotation Type PermissionsAllowed

@Documented @Retention(RUNTIME) @Target({TYPE,METHOD}) @Repeatable(List.class) public @interface PermissionsAllowed
Lists one or more required permissions that must be granted.

  • 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 the 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 the 'getResource' method: 
       @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 access to the resource. It is also possible to define permission actions that are permitted for the resource. Consider the `getResource` method: 
       @PermissionsAllowed({"resource:crud", "resource:retrieve", "system-resource:retrieve"})
 public Resource getResource() {
     // business logic
 }
      Two StringPermission permissions will be created: 
       var pem1 = new StringPermission("resource", "crud", "retrieve");
 var pem2 = new StringPermission("system-resource", "retrieve");
      The permission check will pass if either pem1 or pem2 implies user permissions. It is also possible to combine permissions with and without actions 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");
      Alternatively, when multiple required permissions must be listed, you can repeat the annotation, for example: 
       @PermissionsAllowed("create")
 @PermissionsAllowed("update")
 public Resource createOrUpdate(Long id) {
          // business logic
 }
      Returns:
      permissions
      See Also:

    • inclusive

      boolean inclusive
      Choose a relation between multiple permissions specified in value(). By default, at least one of permissions must be granted. You can request that all of the listed permissions by setting the `inclusive` property to `true`. For example: 
       @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 imply 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(). Consider the following three classes: 
       class ResourceIdentity { }
 class User extends ResourceIdentity { }
 class Admin extends ResourceIdentity { }
      Next, consider the secured 'getResource' method: 
       @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, the parameters user1 and admin1 are marked 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 note that:
      • The constructor parameter names user1 and admin1 must match respective PermissionsAllowed#params
      • `ResourceIdentity` can also be used as a constructor parameter data type
      When this annotation is used as the class-level annotation, it applies to every secured method in the class. 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) {
     }

     ...
 }
      The constructor parameter param1 refers to the admin1#param1 secured method parameter and the constructor parameter param3 refers 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 to create a permission specified in 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