OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

* WebSocket API: Add sending access token through sub-protocols header

Refs https://github.com/openhab/openhab-core/pull/4515.

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

* Update configuration/websocket.md

Signed-off-by: Florian Hotze <dev@florianhotze.com>

---------

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>
Signed-off-by: Florian Hotze <dev@florianhotze.com>
pull/2400/merge
Florian Hotze 2025-01-05 11:55:21 +01:00 committed by GitHub
parent 44afc86b8f
commit a27d468310
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
configuration/websocket.md
View File

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