[security.websocket]

The Origin check on WebSocket upgrades, which stops other websites from opening sockets with your visitors' cookies.

[security.websocket]
check_origin = true      # the default

Browsers let any page open a WebSocket to any server and send that server's cookies with it (cross-site WebSocket hijacking). The upgrade is a GET, so CSRF protection alone would not cover it: GioJS judges every upgrade like an unsafe request instead.

Reference

Behavior

• Independent of [security.csrf] enabled: turning CSRF protection off because your forms carry tokens leaves this check on, since form tokens do nothing for WebSockets.
• It shares the CSRF lists: trusted_origins are accepted here too, and exempt paths skip this check as well - exempt a public WebSocket API meant to be used from any site.
• A refusal is a 403 with a plain-text body naming the setting to change (cross-site WebSocket upgrade blocked by CSRF protection - ...).

Startup warnings

Examples

A public WebSocket API

Keep the check for the app's own sockets and open one path to every site:

[security.csrf]
exempt = ["/api/public-feed"]

A client on another origin

[security.csrf]
trusted_origins = ["https://dashboard.example.com"]

Good to know

• A socket accepted here still has to pass its route's wsHandler, which can check the session and refuse it. See Authenticating connections.
• With [websocket] enabled = false upgrades are answered 501. This check still runs before that, so a cross-site upgrade gets 403.

Related

• Security guide: WebSocket origin checks
• [security.csrf]
• [websocket]
• WebSockets

Version history