From 066ed22fafb5275574ce949fad6b5d1bc5649f16 Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Sat, 4 Jan 2025 22:39:53 +0100 Subject: [PATCH 1/2] WebSocket API: Add sending access token through sub-protocols header Refs https://github.com/openhab/openhab-core/pull/4515. Signed-off-by: Florian Hotze --- configuration/websocket.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/configuration/websocket.md b/configuration/websocket.md index 80cea4b6e8..408270b694 100644 --- 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 sent with the initial request. +There are two options to send the access token: + +1. Through the `Sec-WebSocket-Protocol` header:
+ As browsers cannot add `Authorization` headers to WebSocket requests but can specify WebSocket sub-protocols to send with the request.
+ 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).
+ +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 From 9c5d5be12bf70748a0a9ecaf15e471f355e88ebd Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Sun, 5 Jan 2025 10:17:22 +0100 Subject: [PATCH 2/2] Update configuration/websocket.md Signed-off-by: Florian Hotze --- configuration/websocket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/websocket.md b/configuration/websocket.md index 408270b694..7f1654b579 100644 --- a/configuration/websocket.md +++ b/configuration/websocket.md @@ -14,7 +14,7 @@ All messages on the WebSocket connection are JSON encoded text-messages. 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`. -To prevent unauthorized use of the connection, an access token has to sent with the initial request. +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: