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]>

Author: florian-h05

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