WebSockets Next: Show how to map request headers to Authorization header that OIDC Bearer token authentication require

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

@@ -998,6 +998,66 @@ public class ProductEndpoint {
 <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.
 
+==== Bearer token authentication
+
+The xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication] expects that bearer tokens are passed in the `Authorization` header during the initial HTTP handshake.
+While we recommend to use WebSocket clients that support setting custom headers in the initial HTTP handshake, there are users that rely on https://websockets.spec.whatwg.org/#the-websocket-interface[WebSockets API].
+In this API, the HTTP `Sec-WebSocket-Protocol` request header is the only header that users can configure.
+We have seen users to take advantage of this header for purpose which it is not intended like in the example below:
+
+[source,javascript]
+----
+const token = getBearerToken()
+const socket = new WebSocket("wss://" + location.host + "/chat/" + username, ["bearer", token]); <1>
+----
+<1> Indicate 2 sub-protocols supported by the client, the `bearer` sub-protocol and the token sub-protocol.
+
+The WebSocket server can also be configured with supported sub-protocols:
+
+[source, properties]
+----
+quarkus.websockets-next.server.supported-subprotocols=bearer
+----
+<1> The `bearer` sub-protocol matches the sub-protocol option passed to the client in previous example.
+
+In Quarkus, it is possible to map HTTP server request headers to a different headers, for example:
+
+[source, java]
+----
+package io.quarkus.websockets.next.test.security;
+
+import static io.quarkus.websockets.next.HandshakeRequest.SEC_WEBSOCKET_PROTOCOL;
+import static io.vertx.core.http.HttpHeaders.AUTHORIZATION;
+
+import jakarta.enterprise.event.Observes;
+
+import io.vertx.ext.web.Router;
+
+public class WebSocketTokenHeaderHandler {
+
+    private static final String BEARER_PROTOCOL = "bearer";
+    private static final String TOKEN_PREFIX = BEARER_PROTOCOL + ",";
+
+    void observe(@Observes Router router) {
+        router.get().order(-250).handler(routingContext -> {
+            String webSocketProtocol = routingContext.request().headers().get(SEC_WEBSOCKET_PROTOCOL);
+            if (webSocketProtocol != null && webSocketProtocol.startsWith(TOKEN_PREFIX)) {
+                routingContext.request().headers().remove(SEC_WEBSOCKET_PROTOCOL);
+                routingContext.request().headers().add(SEC_WEBSOCKET_PROTOCOL, BEARER_PROTOCOL);
+                String token = webSocketProtocol.substring(TOKEN_PREFIX.length());
+                routingContext.request().headers().add(AUTHORIZATION, "Bearer " + token);
+            }
+            routingContext.next();
+        });
+    }
+
+}
+----
+<1> Set the `Authorization` header to a bearer token provided in a different HTTP request header.
+
+WARNING: Purpose of this example is to show that currently, it is possible to create the `Authorization` header from other request headers.
+This way, users that go down this path will know how to configure the server side.
+
 === Inspect and/or reject HTTP upgrade
 
 To inspect an HTTP upgrade, you must provide a CDI bean implementing the `io.quarkus.websockets.next.HttpUpgradeCheck` interface.

integration-tests/oidc-dev-services/pom.xml

@@ -23,6 +23,10 @@
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-oidc</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-websockets-next</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-junit5</artifactId>
@@ -76,6 +80,19 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-websockets-next-deployment</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
     </dependencies>
 
     <build>

integration-tests/oidc-dev-services/src/main/java/io/quarkus/it/oidc/dev/services/ChatWebSocket.java

@@ -0,0 +1,28 @@
+package io.quarkus.it.oidc.dev.services;
+
+import jakarta.inject.Inject;
+
+import io.quarkus.security.Authenticated;
+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
+@WebSocket(path = "/chat/{username}")
+public class ChatWebSocket {
+
+    @Inject
+    SecurityIdentity identity;
+
+    @OnOpen
+    public String onOpen() {
+        return "opened";
+    }
+
+    @OnTextMessage
+    public String echo(String message) {
+        return message + " " + identity.getPrincipal().getName();
+    }
+
+}

integration-tests/oidc-dev-services/src/main/java/io/quarkus/it/oidc/dev/services/WebSocketTokenHeaderHandler.java

@@ -0,0 +1,28 @@
+package io.quarkus.it.oidc.dev.services;
+
+import static io.quarkus.websockets.next.HandshakeRequest.SEC_WEBSOCKET_PROTOCOL;
+import static io.vertx.core.http.HttpHeaders.AUTHORIZATION;
+
+import jakarta.enterprise.event.Observes;
+
+import io.vertx.ext.web.Router;
+
+public class WebSocketTokenHeaderHandler {
+
+    private static final String BEARER_PROTOCOL = "bearer";
+    private static final String TOKEN_PREFIX = BEARER_PROTOCOL + ",";
+
+    void observe(@Observes Router router) {
+        router.get().order(-250).handler(routingContext -> {
+            String webSocketProtocol = routingContext.request().headers().get(SEC_WEBSOCKET_PROTOCOL);
+            if (webSocketProtocol != null && webSocketProtocol.startsWith(TOKEN_PREFIX)) {
+                routingContext.request().headers().remove(SEC_WEBSOCKET_PROTOCOL);
+                routingContext.request().headers().add(SEC_WEBSOCKET_PROTOCOL, BEARER_PROTOCOL);
+                String token = webSocketProtocol.substring(TOKEN_PREFIX.length());
+                routingContext.request().headers().add(AUTHORIZATION, "Bearer " + token);
+            }
+            routingContext.next();
+        });
+    }
+
+}

integration-tests/oidc-dev-services/src/main/resources/application.properties

@@ -1,6 +1,8 @@
 quarkus.oidc.devservices.enabled=true
 quarkus.oidc.devservices.roles.Ronald=admin
 
+quarkus.websockets-next.server.supported-subprotocols=bearer
+
 %code-flow.quarkus.oidc.devservices.roles.alice=admin,user
 %code-flow.quarkus.oidc.devservices.roles.bob=user
 %code-flow.quarkus.oidc.application-type=web-app

integration-tests/oidc-dev-services/src/test/java/io/quarkus/it/oidc/dev/services/WebSocketOidcTest.java

@@ -0,0 +1,88 @@
+package io.quarkus.it.oidc.dev.services;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.net.URI;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.concurrent.atomic.AtomicReference;
+
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.test.common.http.TestHTTPResource;
+import io.quarkus.test.junit.QuarkusTest;
+import io.quarkus.test.oidc.client.OidcTestClient;
+import io.vertx.core.Vertx;
+import io.vertx.core.http.WebSocket;
+import io.vertx.core.http.WebSocketClient;
+import io.vertx.core.http.WebSocketConnectOptions;
+
+@QuarkusTest
+public class WebSocketOidcTest {
+
+    @TestHTTPResource("/chat")
+    URI uri;
+
+    @Inject
+    Vertx vertx;
+
+    private static final OidcTestClient oidcTestClient = new OidcTestClient();
+
+    @AfterAll
+    public static void close() {
+        oidcTestClient.close();
+    }
+
+    @Test
+    public void testDocumentedTokenPropagationUsingSubProtocol()
+            throws InterruptedException, ExecutionException, TimeoutException {
+        // verify that handler documented in WebSockets Next reference
+        // propagates "Sec-WebSocket-Protocol" as Authorization header
+        // and authentication is successful
+        CountDownLatch connectedLatch = new CountDownLatch(1);
+        CountDownLatch messagesLatch = new CountDownLatch(2);
+        List<String> messages = new CopyOnWriteArrayList<>();
+        AtomicReference<WebSocket> ws1 = new AtomicReference<>();
+        WebSocketClient client = vertx.createWebSocketClient();
+        WebSocketConnectOptions options = new WebSocketConnectOptions();
+        options.setHost(uri.getHost());
+        options.setPort(uri.getPort());
+        options.setURI(uri.getPath() + "/IF");
+        options.setSubProtocols(List.of("bearer", oidcTestClient.getAccessToken("alice", "alice")));
+        try {
+            client
+                    .connect(options)
+                    .onComplete(r -> {
+                        if (r.succeeded()) {
+                            WebSocket ws = r.result();
+                            ws.textMessageHandler(msg -> {
+                                messages.add(msg);
+                                messagesLatch.countDown();
+                            });
+                            // We will use this socket to write a message later on
+                            ws1.set(ws);
+                            connectedLatch.countDown();
+                        } else {
+                            throw new IllegalStateException(r.cause());
+                        }
+                    });
+            assertTrue(connectedLatch.await(5, TimeUnit.SECONDS));
+            ws1.get().writeTextMessage("hello");
+            assertTrue(messagesLatch.await(5, TimeUnit.SECONDS), "Messages: " + messages);
+            assertEquals(2, messages.size(), "Messages: " + messages);
+            assertEquals("opened", messages.get(0));
+            assertEquals("hello alice", messages.get(1));
+        } finally {
+            client.close().toCompletionStage().toCompletableFuture().get(5, TimeUnit.SECONDS);
+        }
+    }
+
+}