Support permission checkers for WebSockets Next

Author: michalvavrik

docs/src/main/asciidoc/websockets-next-reference.adoc

@@ -185,8 +185,12 @@ public class MyWebSocket {
 
 ==== Request context
 
-If an endpoint is annotated with `@RequestScoped`, or with a security annotation (such as `@RolesAllowed`), or depends directly or indirectly on a `@RequestScoped` bean, or on a bean annotated with a security annotation, then each WebSocket endpoint callback method execution is associated with a new _request context_.
-The request context is active during endpoint callback invocation.
+Each WebSocket endpoint callback method execution is associated with a new _request context_ (activate CDI request context) if the endpoint is:
+
+* Annotated with the `@RequestScoped` annotation.
+* Has a method annotated with a security annotation such as `@RolesAllowed`.
+* Depends directly or indirectly on a `@RequestScoped` bean.
+* Depends directly or indirectly on a CDI beans secured with a standard security annotation.
 
 TIP: It is also possible to set the `quarkus.websockets-next.server.activate-request-context` config property to `always`. In this case, the request context is always activated when an endpoint callback is invoked.
 
@@ -783,6 +787,67 @@ class MyBean {
 [[websocket-next-security]]
 === Security
 
+Security capabilities are provided by the Quarkus Security extension.
+Any xref:security-identity-providers.adoc[Identity provider] can be used to convert authentication credentials attached to a secure HTTP upgrade into a `SecurityIdentity` instance.
+The `SecurityIdentity` is then associated with the websocket connection.
+Authorization options are demonstrated in following sections.
+
+NOTE: When OpenID Connect extension is used and token expires, Quarkus automatically closes connection.
+
+[[secure-http-upgrade]]
+==== Secure HTTP upgrade
+
+An HTTP upgrade is secured when standard security annotation is placed on an endpoint class or an HTTP Security policy is defined.
+The advantage of securing HTTP upgrade is less processing, the authorization is performed early and only once.
+You should always prefer HTTP upgrade security unless, like in the example above, you need to perform an action on error or a security check based on the payload.
+
+.Use standard security annotation to secure an HTTP upgrade
+[source, java]
+----
+package io.quarkus.websockets.next.test.security;
+
+import io.quarkus.security.Authenticated;
+import jakarta.inject.Inject;
+
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.websockets.next.OnOpen;
+import io.quarkus.websockets.next.OnTextMessage;
+import io.quarkus.websockets.next.WebSocket;
+
+@Authenticated <1>
+@WebSocket(path = "/end")
+public class Endpoint {
+
+    @Inject
+    SecurityIdentity currentIdentity;
+
+    @OnOpen
+    String open() {
+        return "ready";
+    }
+
+    @OnTextMessage
+    String echo(String message) {
+        return message;
+    }
+}
+----
+<1> Initial HTTP handshake ends with the 401 status for anonymous users.
+You can also redirect the handshake request on authorization failure with the `quarkus.websockets-next.server.security.auth-failure-redirect-url` configuration property.
+
+IMPORTANT: HTTP upgrade is only secured when a security annotation is declared on an endpoint class next to the `@WebSocket` annotation.
+Placing a security annotation on an endpoint bean will not secure bean methods, only the HTTP upgrade.
+You must always verify that your endpoint is secured as intended.
+
+.Use HTTP Security policy to secure an HTTP upgrade
+[source,properties]
+----
+quarkus.http.auth.permission.http-upgrade.paths=/end
+quarkus.http.auth.permission.http-upgrade.policy=authenticated
+----
+
+==== Secure WebSocket endpoint callback methods
+
 WebSocket endpoint callback methods can be secured with security annotations such as `io.quarkus.security.Authenticated`,
 `jakarta.annotation.security.RolesAllowed` and other annotations listed in the xref:security-authorize-web-endpoints-reference.adoc#standard-security-annotations[Supported security annotations] documentation.
 
@@ -828,60 +893,108 @@ public class Endpoint {
 <1> The echo callback method can only be invoked if the current security identity has an `admin` role.
 <2> The error handler is invoked in case of the authorization failure.
 
-`SecurityIdentity` is initially created during a secure HTTP upgrade and associated with the websocket connection.
+==== Secure server endpoints with permission checkers
 
-NOTE: When OpenID Connect extension is used and token expires, Quarkus automatically closes connection.
+WebSocket endpoints can be secured with the xref:security-authorize-web-endpoints-reference.adoc#permission-checker[permission checkers].
+We recommend to <<secure-http-upgrade>> rather than individual endpoint methods. For example:
 
-=== Secure HTTP upgrade
+.Example of a WebSocket endpoint with secured HTTP upgrade
+[source, java]
+----
+package io.quarkus.websockets.next.test.security;
 
-An HTTP upgrade is secured when standard security annotation is placed on an endpoint class or an HTTP Security policy is defined.
-The advantage of securing HTTP upgrade is less processing, the authorization is performed early and only once.
-You should always prefer HTTP upgrade security unless, like in th example above, you need to perform action on error.
+import io.quarkus.security.PermissionsAllowed;
+import io.quarkus.websockets.next.OnTextMessage;
+import io.quarkus.websockets.next.WebSocket;
 
-.Use standard security annotation to secure an HTTP upgrade
+@PermissionsAllowed("product:premium")
+@WebSocket(path = "/product/premium")
+public class PremiumProductEndpoint {
+
+    @OnTextMessage
+    PremiumProduct getPremiumProduct(int productId) {
+        return new PremiumProduct(productId);
+    }
+
+}
+----
+
+.Example of a permission checker authorizing the HTTP upgrade
 [source, java]
 ----
 package io.quarkus.websockets.next.test.security;
 
-import io.quarkus.security.Authenticated;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.security.PermissionChecker;
+import io.quarkus.vertx.http.runtime.security.HttpSecurityUtils;
+import io.vertx.ext.web.RoutingContext;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class PermissionChecker {
+
+    @PermissionChecker("product:premium")
+    public boolean canGetPremiumProduct(SecurityIdentity securityIdentity) { <1>
+        String username = currentIdentity.getPrincipal().getName();
+
+        RoutingContext routingContext = HttpSecurityUtils.getRoutingContextAttribute(securityIdentity);
+        String initialHttpUpgradePath = routingContext == null ? null : routingContext.normalizedPath();
+        if (!isUserAllowedToAccessPath(initialHttpUpgradePath, username)) {
+            return false;
+        }
+
+        return isPremiumCustomer(username);
+    }
+
+}
+----
+<1> A permission checker authorizing an HTTP upgrade must declare exactly one method parameter, the `SecurityIdentity`.
+
+If the security check performs payload-aware authorization, it is also possible to run check on every message. For example:
+
+[source, java]
+----
+package io.quarkus.websockets.next.test.security;
+
+import io.quarkus.security.PermissionChecker;
+import io.quarkus.security.PermissionsAllowed;
 import jakarta.inject.Inject;
 
+import io.quarkus.security.ForbiddenException;
 import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.websockets.next.OnError;
 import io.quarkus.websockets.next.OnOpen;
 import io.quarkus.websockets.next.OnTextMessage;
 import io.quarkus.websockets.next.WebSocket;
 
-@Authenticated <1>
-@WebSocket(path = "/end")
-public class Endpoint {
+@WebSocket(path = "/product")
+public class ProductEndpoint {
+
+    private record Product(int id, String name) {}
 
     @Inject
     SecurityIdentity currentIdentity;
 
-    @OnOpen
-    String open() {
-        return "ready";
-    }
-
+    @PermissionsAllowed("product:get")
     @OnTextMessage
-    String echo(String message) {
-        return message;
+    Product getProduct(int productId) { <1>
+        return new Product(productId, "Product " + productId);
     }
-}
-----
-<1> Initial HTTP handshake ends with the 401 status for anonymous users.
-You can also redirect the handshake request on authorization failure with the `quarkus.websockets-next.server.security.auth-failure-redirect-url` configuration property.
 
-IMPORTANT: HTTP upgrade is only secured when a security annotation is declared on an endpoint class next to the `@WebSocket` annotation.
-Placing a security annotation on an endpoint bean will not secure bean methods, only the HTTP upgrade.
-You must always verify that your endpoint is secured as intended.
+    @OnError
+    String error(ForbiddenException t) { <2>
+        return "forbidden:" + currentIdentity.getPrincipal().getName();
+    }
 
-.Use HTTP Security policy to secure an HTTP upgrade
-[source,properties]
-----
-quarkus.http.auth.permission.http-upgrade.paths=/end
-quarkus.http.auth.permission.http-upgrade.policy=authenticated
+    @PermissionChecker("product:get")
+    boolean canGetProduct(int productId) {
+        String username = currentIdentity.getPrincipal().getName();
+        return currentIdentity.hasRole("admin") || canUserGetProduct(productId, username);
+    }
+}
 ----
+<1> The `getProduct` callback method can only be invoked if the current security identity has an `admin` role or the user is allowed to get the product detail.
+<2> The error handler is invoked in case of the authorization failure.
 
 === Inspect and/or reject HTTP upgrade
 

extensions/security/runtime/src/main/java/io/quarkus/security/runtime/QuarkusPermissionSecurityIdentityAugmentor.java

@@ -1,6 +1,8 @@
 package io.quarkus.security.runtime;
 
 import java.security.Permission;
+import java.util.Map;
+import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
@@ -33,33 +35,43 @@ public Throwable apply(Throwable throwable) {
             return new ForbiddenException(throwable);
         }
     };
+    // keep in sync with HttpSecurityUtils
+    private static final String ROUTING_CONTEXT_ATTRIBUTE = "quarkus.http.routing.context";
 
-    private final BlockingSecurityExecutor blockingExecutor;
+    private final BiFunction<SecurityIdentity, Permission, Uni<Boolean>> permissionChecker;
 
     QuarkusPermissionSecurityIdentityAugmentor(BlockingSecurityExecutor blockingExecutor) {
-        this.blockingExecutor = blockingExecutor;
+        this.permissionChecker = new BiFunction<SecurityIdentity, Permission, Uni<Boolean>>() {
+            @Override
+            public Uni<Boolean> apply(SecurityIdentity finalIdentity, Permission requiredpermission) {
+                if (requiredpermission instanceof QuarkusPermission<?> quarkusPermission) {
+                    return quarkusPermission
+                            .isGranted(finalIdentity, blockingExecutor)
+                            .onFailure(NOT_A_FORBIDDEN_EXCEPTION).transform(WRAP_WITH_FORBIDDEN_EXCEPTION);
+                }
+                return Uni.createFrom().item(false);
+            }
+        };
     }
 
     @Override
-    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
+    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context,
+            Map<String, Object> attributes) {
         if (identity.isAnonymous()) {
             return Uni.createFrom().item(identity);
         }
 
-        return Uni.createFrom().item(QuarkusSecurityIdentity
-                .builder(identity)
-                .addPermissionChecker(new Function<>() {
-                    @Override
-                    public Uni<Boolean> apply(Permission requiredpermission) {
-                        if (requiredpermission instanceof QuarkusPermission<?> quarkusPermission) {
-                            return quarkusPermission
-                                    .isGranted(identity, blockingExecutor)
-                                    .onFailure(NOT_A_FORBIDDEN_EXCEPTION).transform(WRAP_WITH_FORBIDDEN_EXCEPTION);
-                        }
-                        return Uni.createFrom().item(false);
-                    }
-                })
-                .build());
+        var identityBuilder = QuarkusSecurityIdentity.builder(identity).addPermissionCheckerWithIdentity(permissionChecker);
+        if (attributes.containsKey(ROUTING_CONTEXT_ATTRIBUTE)) {
+            // propagates RoutingContext, useful when CDI request context is not active or the RoutingContext is not there
+            identityBuilder.addAttribute(ROUTING_CONTEXT_ATTRIBUTE, attributes.get(ROUTING_CONTEXT_ATTRIBUTE));
+        }
+        return Uni.createFrom().item(identityBuilder.build());
+    }
+
+    @Override
+    public Uni<SecurityIdentity> augment(SecurityIdentity identity, AuthenticationRequestContext context) {
+        return augment(identity, context, Map.of());
     }
 
     @Override

extensions/security/runtime/src/main/java/io/quarkus/security/runtime/QuarkusSecurityIdentity.java

@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
@@ -31,7 +32,7 @@ private QuarkusSecurityIdentity(Builder builder) {
         this.roles = Collections.unmodifiableSet(builder.roles);
         this.credentials = Collections.unmodifiableSet(builder.credentials);
         this.attributes = Collections.unmodifiableMap(builder.attributes);
-        this.permissionCheckers = Collections.unmodifiableList(builder.permissionCheckers);
+        this.permissionCheckers = getPermissionCheckers(builder, this);
         this.anonymous = builder.anonymous;
     }
 
@@ -141,6 +142,18 @@ public Uni<Boolean> apply(Permission permission) {
         return builder;
     }
 
+    private static List<Function<Permission, Uni<Boolean>>> getPermissionCheckers(Builder builder, SecurityIdentity identity) {
+        for (var checker : builder.permissionCheckersWithIdentity) {
+            builder.permissionCheckers.add(new Function<Permission, Uni<Boolean>>() {
+                @Override
+                public Uni<Boolean> apply(Permission permission) {
+                    return checker.apply(identity, permission);
+                }
+            });
+        }
+        return Collections.unmodifiableList(builder.permissionCheckers);
+    }
+
     public static class Builder {
 
         Principal principal;
@@ -149,6 +162,7 @@ public static class Builder {
         Set<Permission> permissions = new HashSet<>();
         Map<String, Object> attributes = new HashMap<>();
         List<Function<Permission, Uni<Boolean>>> permissionCheckers = new ArrayList<>();
+        List<BiFunction<SecurityIdentity, Permission, Uni<Boolean>>> permissionCheckersWithIdentity = new ArrayList<>();
         private boolean anonymous;
         boolean built = false;
 
@@ -268,6 +282,19 @@ public Builder addPermissionChecker(Function<Permission, Uni<Boolean>> function)
             return this;
         }
 
+        /**
+         * Internal method similar to {@link #addPermissionChecker(Function)}.
+         * Only difference is that permission checker is defined on both required permission and the identity this
+         * builder creates.
+         */
+        Builder addPermissionCheckerWithIdentity(BiFunction<SecurityIdentity, Permission, Uni<Boolean>> function) {
+            if (built) {
+                throw new IllegalStateException();
+            }
+            permissionCheckersWithIdentity.add(function);
+            return this;
+        }
+
         /**
          * Adds a permission check functions.
          *

extensions/security/spi/src/main/java/io/quarkus/security/spi/PermissionsAllowedMetaAnnotationBuildItem.java

@@ -49,7 +49,7 @@ public List<AnnotationInstance> getTransitiveInstances() {
         return transitiveInstances;
     }
 
-    private boolean hasPermissionsAllowed(List<AnnotationInstance> instances) {
+    public boolean hasPermissionsAllowed(List<AnnotationInstance> instances) {
         return instances.stream().anyMatch(ai -> metaAnnotationNames.contains(ai.name()));
     }
 

extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityUtils.java

@@ -12,6 +12,7 @@
 import io.vertx.ext.web.RoutingContext;
 
 public final class HttpSecurityUtils {
+    // keep in sync with QuarkusPermissionSecurityIdentityAugmentor
     public final static String ROUTING_CONTEXT_ATTRIBUTE = "quarkus.http.routing.context";
     static final String SECURITY_IDENTITIES_ATTRIBUTE = "io.quarkus.security.identities";
     static final String COMMON_NAME = "CN";
@@ -55,7 +56,11 @@ public static RoutingContext getRoutingContextAttribute(AuthenticationRequest re
     }
 
     public static RoutingContext getRoutingContextAttribute(SecurityIdentity identity) {
-        return identity.getAttribute(RoutingContext.class.getName());
+        RoutingContext routingContext = identity.getAttribute(RoutingContext.class.getName());
+        if (routingContext != null) {
+            return routingContext;
+        }
+        return identity.getAttribute(ROUTING_CONTEXT_ATTRIBUTE);
     }
 
     public static RoutingContext getRoutingContextAttribute(Map<String, Object> authenticationRequestAttributes) {