websockets.security

Security mechansism when working with WebSockets.

There are a some risks involved when it comes to WebSockets as they behave different than HTTP.

Same-Origin Policy (SOP)

WebSockets are not protected through the Same-Origin Policy (SOP). That means, origins that are not our domain can connect to the WebSocket too. If a user is tricked to visit a attacker-controlled website, the page can establish a websocket connection to us, on behalf of the user - if we rely solely on the session ID. Altough the attacker can not access the cookie that contains the session ID, the browser will happily sent it to the websocket server, creating a connection that is now controlled by the attacker. See [2] and [3] for examples.

To prevent that we can:

(a) check the origin against a list of allowed origins. The user’s browser controls the origin and can not be overwritten by the attacker (when in the context of the user’s browser, it can however easily be spoofed when using a tool such as curl).

(b) issue a one-time token that is not guessable for an attacker - similar to a CSRF token. The token is issued before initiating a WebSocket connection and must be presented when creating the WebSocket connection.

Authentication

By default, WebSockets are not authenticated and any connection must - if required - be manually be authenticated. See [1] for a list of options.

Resources

Exceptions

WebsocketSecurityError

A security check failed, the connection should not be established.

WebsocketTokenMismatch

Presented token does not match stored token.

NoWebsocketTokenPresented

Connection did not present any token to verify.

NoWebsocketTokenStored

No token in session to verify presented token against.

Functions

consume_websocket_token(→ str)

Consume websocket token.

Module Contents

exception websockets.security.WebsocketSecurityError[source]

Bases: Exception

A security check failed, the connection should not be established.

exception websockets.security.WebsocketTokenMismatch[source]

Bases: WebsocketSecurityError

Presented token does not match stored token.

exception websockets.security.NoWebsocketTokenPresented[source]

Bases: WebsocketSecurityError

Connection did not present any token to verify.

This is most likely if we (a) did not expect this connection or (b) forgot to supply the token when connecting.

exception websockets.security.NoWebsocketTokenStored[source]

Bases: WebsocketSecurityError

No token in session to verify presented token against.

This is most likely if we (a) did not expect this connection or (b) forgot to store the token in the session before connecting.

websockets.security.consume_websocket_token(path: str, session: BrowserSession | dict[str, Any], session_key: str = 'websocket_token') str[source]

Consume websocket token.

If presented token matches the stored token, this method will remove the token from the session. In any other case, it will raise a specific WebsocketSecurityError.