diff --git a/docs/src/main/asciidoc/security-overview.adoc b/docs/src/main/asciidoc/security-overview.adoc index c4620b815fba1f..81217b8b412c17 100644 --- a/docs/src/main/asciidoc/security-overview.adoc +++ b/docs/src/main/asciidoc/security-overview.adoc @@ -53,6 +53,12 @@ For guidance on testing Quarkus Security features and ensuring that your Quarkus == More about security features in Quarkus +=== WebSockets Next security + +The `quarkus-websockets-next` extension provides a modern, efficient implementation of the WebSocket API. +It also provides an integration with Quarkus security. +For more information, see the xref:websockets-next-reference.adoc#websocket-next-security[Security] section of the Quarkus "WebSockets Next reference" guide. + [[cross-origin-resource-sharing]] === Cross-origin resource sharing diff --git a/docs/src/main/asciidoc/websockets-next-reference.adoc b/docs/src/main/asciidoc/websockets-next-reference.adoc index 3e76df74bf9692..62039a09f81147 100644 --- a/docs/src/main/asciidoc/websockets-next-reference.adoc +++ b/docs/src/main/asciidoc/websockets-next-reference.adoc @@ -574,6 +574,67 @@ void pong(Buffer data) { } ---- +[[websocket-next-security]] +== Security + +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. + +For example: + +[source, java] +---- +package io.quarkus.websockets.next.test.security; + +import jakarta.annotation.security.RolesAllowed; +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; + +@WebSocket(path = "/end") +public class Endpoint { + + @Inject + SecurityIdentity currentIdentity; + + @OnOpen + String open() { + return "ready"; + } + + @RolesAllowed("admin") + @OnTextMessage + String echo(String message) { <1> + return message; + } + + @OnError + String error(ForbiddenException t) { <2> + return "forbidden:" + currentIdentity.getPrincipal().getName(); + } +} +---- +<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. + +Currently, for an HTTP upgrade be secured, users must configure an HTTP policy protecting the HTTP upgrade path. +For example, to secure the `open()` method in the above websocket endpoint, one can add the following authentication policy: + +[source,properties] +---- +quarkus.http.auth.permission.secured.paths=/end +quarkus.http.auth.permission.secured.policy=authenticated +---- + +Other options for securing HTTP upgrade requests, such as using the security annotations, will be explored in the future. + [[websocket-next-configuration-reference]] == Configuration reference