Merge pull request #54 from michalvavrik/feature/change-default-permi…

…ssions-allowed-behavior

Detect permission constructor parameters based on formal method names match with a method secured by the @PermissionsAllowed annotation

src/main/java/io/quarkus/security/PermissionsAllowed.java

@@ -32,38 +32,50 @@
 
     /**
      * Constant value for {@link #params()} indicating that the constructor parameters of the {@link #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:
-     *
+     * should be autodetected based on formal parameter names. For example, consider following method secured with this
+     * annotation:
+     * <pre>
+     * {@code
+     * &#64;PermissionsAllowed(value = "resource:retrieve", permission = UserPermission.class)
+     * public Resource getResource(String param1, String param2, String param3) {
+     *      // business logic
+     * }
+     * }
+     * </pre>
+     * The {@code getResource} method parameters {@code param1} and {@code param3} will be
+     * matched with the {@code UserPermission} constructor parameters {@code param1} and {@code param3}.
      * <pre>
+     * {@code
      * public class UserPermission extends Permission {
      *
-     *     private final User user;
-     *
-     *     public UserPermission(String name, User user) {
-     *         super(name);
-     *         this.user = user;
+     *     public UserPermission(String name, String param3, String param1) {
+     *         ...
      *     }
      *
      *     ...
      * }
-     * </pre>
+     * }
+     * 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:
+     * <pre>
+     * {@code
+     * record BeanParam2(String param1, String param2) {}
+     * record BeanParam3(String param3) {}
+     * record BeanParam1(BeanParam2 beanParam2, BeanParam3 beanParam3) {
      *
-     * Constructor parameter {@code user} is in fact object passed to a secured method.
-     * In the example below, {@code user1} parameter of the 'getResource' method is passed to the constructor.
+     * }
      *
-     * <pre>
-     * &#64;PermissionsAllowed(permission = UserPermission.class, value = "resource")
-     * public Resource getResource(User user1) {
-     *     // business logic
+     * &#64;PermissionsAllowed(value = "resource:retrieve", permission = UserPermission.class)
+     * public Resource getResource(BeanParam1 beanParam) {
+     *      // business logic
      * }
-     * </pre>
      *
-     * 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 {@link #params()} for more complex matching.
+     * }
+     * }
+     * </pre>
+     * In this example, resolution of the {@code param1} and {@code param3} formal parameters is unambiguous.
+     * For more complex scenarios, we suggest to specify {@link #params()} explicitly.
      */
     String AUTODETECTED = "<<autodetected>>";
 
@@ -204,6 +216,45 @@
      * <b>WARNING:</b> "params" attribute is only supported in the scenarios explicitly named in the Quarkus documentation.
      * </p>
      *
+     * Method parameter fields or methods can be passed to a Permission constructor as well.
+     * Consider the following secured method and its parameters:
+     * <pre>
+     * {@code
+     * &#64;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 { }
+     * }
+     * </pre>
+     *
+     * The corresponding {@code UserPermission} constructor would look like this:
+     *
+     * <pre>
+     * public class UserPermission extends Permission {
+     *
+     *     public UserPermission(String name, String param1, String param3) {
+     *     }
+     *
+     *     ...
+     * }
+     * </pre>
+     *
+     * Here, the constructor parameter {@code param1} refers to the {@code admin1#param1} secured method parameter
+     * and the constructor parameter {@code param3} to the {@code user1#getParam3} secured method parameter.
+     *
      * @see #AUTODETECTED
      *
      * @return constructor parameters passed to the {@link #permission()}