WebSocket API: Add sending access token through sub-protocols header (#…

…2442) * WebSocket API: Add sending access token through sub-protocols header Refs openhab/openhab-core#4515. Signed-off-by: Florian Hotze <[email protected]> * Update configuration/websocket.md Signed-off-by: Florian Hotze <[email protected]> --------- Signed-off-by: Florian Hotze <[email protected]> Signed-off-by: Florian Hotze <[email protected]>
openhab · Jan 5, 2025 · a27d468 · a27d468
1 parent 44afc86
commit a27d468
Showing 1 changed file with 13 additions and 4 deletions.
diff --git a/configuration/websocket.md b/configuration/websocket.md
@@ -12,14 +12,23 @@ All messages on the WebSocket connection are JSON encoded text-messages.
 ## Establishing a connection
 
 WebSockets are available on the same ports as the REST API, usually port 8080 for unsecured (ws-protocol) and port 8443 for secured (wss-protocol) connections.
-The connection is established by connecting to  `ws[s]://{URL}:{PORT}/ws?accessToken={TOKEN}`.
+The connection is established by connecting to `ws[s]://{URL}:{PORT}/ws`.
 
-To prevent unauthorized use of the connection an `accessToken` has to be sent with the initial request.
-{TOKEN} can be one of these two:
+To prevent unauthorized use of the connection, an access token has to be sent with the initial request.
+There are two options to send the access token:
+
+1. Through the `Sec-WebSocket-Protocol` header:<br>
+  As browsers cannot add `Authorization` headers to WebSocket requests but can specify WebSocket sub-protocols to send with the request.<br>
+  You need to set the `org.openhab.ws.protocol.default` and `org.openhab.ws.accessToken.base64.${BASE64_TOKEN}` sub-protocols, where `${BASE64_TOKEN}` is the Base64 encoded `${TOKEN}` without `=` padding.
+  The server will respond with the `org.openhab.ws.protocol.default` sub-protocol (as browsers require the server to select one of the provided sub-protocols).<br>
+
+1. Through the `accessToken` query parameter: `ws[s]://{URL}:{PORT}/ws?accessToken={TOKEN}`.
+
+`${TOKEN}` can be one of these two:
 
 1. An API token: `oh.ohwstest.tz1IDPniKLxc0VU4t9tz4GiAiKmc0ZDdMKxhlD5tfviQStM4oNsywrcrUTktPbBE9YQ3wnMBrCqVEIhg7Q`
 
-1. Basic Auth with base64 encoded {USER}:{PASSWORD}: `dXNlcjpwYXNzd29yZA==`
+1. Basic Auth with base64 encoded `{USER}:{PASSWORD}`: `dXNlcjpwYXNzd29yZA==`
 
 ## Using the WebSocket connection