Authenticating WebSocket Connections

Analogy categoryAnalogies

Why WebSocket Auth Is Different from REST

REST APIs typically authenticate every request independently, usually via an Authorization: Bearer <token> header attached to each call, but a WebSocket connection is authenticated once at handshake time and then stays open, sometimes for hours, meaning the server must decide upfront whether to trust the connection for its entire lifetime or build in a mechanism to re-verify it later. Browsers also don't let JavaScript set custom headers on the WebSocket handshake request (new WebSocket() has no headers parameter), which rules out the simple Authorization header pattern REST clients use and forces auth data into the URL, a subprotocol, or a message sent immediately after connecting.

🏏

Cricket analogy: It's like a season ticket being checked once at the turnstile rather than at every single ball bowled; the gate staff must decide the ticket is valid for the entire match, unlike a pay-per-over model that would re-check constantly.

Token-Based Authentication at Handshake

The most common pattern is passing a short-lived JWT or session token as a query parameter on the WebSocket URL (wss://api.example.com/ws?token=eyJ...), which the server validates during the HTTP upgrade request before accepting the connection and rejects with a normal HTTP error status if invalid, closing the door before the socket ever opens. Query parameters land in server access logs and browser history by default, so many teams instead send the token as the very first message immediately after onopen fires, having the server hold the connection in an unauthenticated, message-limited state until it receives and validates that first auth message, then closing it if no valid token arrives within a short grace period.

🏏

Cricket analogy: It's like a stadium checking your ticket QR code at the turnstile before letting you onto the concourse at all, versus letting everyone in first and then walking around checking wristbands afterward, where the first approach avoids letting an invalid ticket-holder ever set foot inside.

javascript

// Server (Node.js, ws) — validating a JWT during the HTTP upgrade
const { WebSocketServer } = require('ws');
const jwt = require('jsonwebtoken');

const wss = new WebSocketServer({ noServer: true });

httpServer.on('upgrade', (req, socket, head) => {
  const url = new URL(req.url, 'https://placeholder');
  const token = url.searchParams.get('token');

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    wss.handleUpgrade(req, socket, head, (ws) => {
      ws.userId = payload.sub;
      wss.emit('connection', ws, req);
    });
  } catch (err) {
    socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
    socket.destroy(); // reject before the socket ever fully opens
  }
});

Per-Message Authorization and Reauth

Authenticating the handshake only proves who connected at that moment; for long-lived connections you still need per-message authorization checks (does this user have permission to join *this specific* room or subscribe to *this specific* channel) since roles and permissions can change mid-session — a user demoted from admin five minutes into a connection shouldn't retain admin-level socket privileges just because the handshake succeeded earlier. Because JWTs are commonly short-lived (minutes to an hour), production systems also need a reauth flow: either the client proactively sends a refreshed token before the old one expires, or the server tracks token expiry and forcibly closes the connection when it lapses, requiring a fresh reconnect with a new token.

🏏

Cricket analogy: It's like a player being cleared to enter the ground at the gate but still needing separate authorization from the umpire before being allowed to bowl a specific over, since eligibility (like an injury substitution rule) can change mid-match after entry.

A common pattern is to store the decoded token's expiry (exp claim) on the socket object at connect time, then run a periodic timer that checks every connected socket and closes any whose token has expired, forcing a clean reconnect with a fresh token rather than letting a stale session linger indefinitely.

Common Pitfalls

A frequent mistake is validating the token only at handshake and then trusting every subsequent message from that socket implicitly, which means a compromised or long-lived socket can act with permissions the user no longer has; another is putting sensitive tokens in URL query strings without also using wss:// (TLS), since a plain ws:// connection sends that token in cleartext, visible to anyone on the network path. Rate-limiting unauthenticated connections is also easy to overlook — an attacker can open thousands of sockets and never send a valid auth message, tying up server memory and file descriptors, so servers should enforce a short grace period (e.g. 5 seconds) after which an unauthenticated socket is forcibly closed.

🏏

Cricket analogy: It's like a ground checking a spectator's ticket once at the gate in the morning and never noticing if they're later caught trying to sneak into the players' pavilion that afternoon, when ongoing checks at each restricted area would have caught it.

Never send authentication tokens over plain ws:// — always use wss:// (WebSocket over TLS), the same as you would never send a password over plain HTTP. A token sent in cleartext over an unencrypted socket can be captured by anyone on the same network segment, including public Wi-Fi.

WebSocket handshakes authenticate once for a long-lived connection, unlike REST's per-request auth model.
Browsers cannot set custom headers on the WebSocket handshake, forcing auth into the URL, a subprotocol, or a post-connect message.
Rejecting an invalid token during the HTTP upgrade (before the socket opens) is safer than accepting first and closing later.
Handshake auth alone isn't enough — per-message authorization must account for permissions that change mid-session.
Short-lived JWTs require an explicit reauth flow or the server must force-close connections on token expiry.
Tokens must be sent only over wss:// (TLS); plain ws:// exposes them in cleartext.
Unauthenticated connections should be rate-limited and force-closed after a short grace period to prevent resource exhaustion.