Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Jan 5, 2025
Merged

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

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
066ed22
WebSocket API: Add sending access token through sub-protocols header
florian-h05 Jan 4, 2025
9c5d5be
Update configuration/websocket.md
florian-h05 Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions configuration/websocket.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
florian-h05 marked this conversation as resolved.
Show resolved Hide resolved
florian-h05 marked this conversation as resolved.
Show resolved Hide resolved
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

Expand Down
Loading