WebSocket Security Basics

Analogy categoryAnalogies

Why WebSocket Security Differs From HTTP

A WebSocket connection begins life as an ordinary HTTP GET request carrying an Upgrade: websocket header, but once the 101 Switching Protocols response comes back, the browser stops applying the same-origin restrictions it uses for fetch() or XMLHttpRequest. Any page, from any origin, can open a WebSocket to your server and the browser will happily attach cookies for that domain. This means the server itself must validate the Origin header during the handshake instead of relying on the browser to block cross-origin attempts.

🏏

Cricket analogy: It's like a stadium gate that checks tickets for the members' enclosure at the main entrance but has no checks once you're inside walking toward the pavilion, so a ground steward, not the turnstile, has to verify your accreditation badge at every doorway, the way MCG security does during an Ashes Test.

Authenticating WebSocket Connections

Because the WebSocket handshake is a single HTTP request, you have exactly one opportunity to attach credentials before the connection becomes a long-lived, bidirectional pipe. Common patterns include passing a short-lived JWT as a query parameter or in the Sec-WebSocket-Protocol header, or relying on an existing session cookie that the server independently re-validates. Query-string tokens are simple but can leak into server access logs, so many teams prefer a two-step flow: authenticate over HTTPS first to get a one-time ticket, then present that ticket during the WebSocket upgrade.

🏏

Cricket analogy: A day-night Test match ticket bought online generates a one-time QR code redeemed at the gate for a physical wristband, similar to exchanging a login session for a short-lived WebSocket ticket instead of reusing the same long-lived credential everywhere.

Transport-Level Protections

Production WebSocket traffic should always use the wss:// scheme, which wraps the connection in TLS exactly like HTTPS does for regular requests. Plain ws:// sends every frame, including auth tokens and application data, in cleartext, which is trivially sniffable on shared networks like coffee-shop Wi-Fi or a compromised router. Browsers also enforce mixed-content rules that block ws:// connections initiated from an https:// page, so serving your app over TLS effectively forces you toward wss:// as well.

🏏

Cricket analogy: Commentary feeds sent over an encrypted broadcast link versus an open radio frequency are the difference between wss:// and ws://; anyone with a scanner near the ground can intercept the unencrypted feed the way an attacker sniffs plaintext WebSocket traffic on open Wi-Fi.

javascript

const WebSocket = require('ws');
const jwt = require('jsonwebtoken');

const ALLOWED_ORIGINS = new Set([
  'https://app.example.com',
  'https://staging.example.com',
]);

const wss = new WebSocket.Server({ noServer: true });

server.on('upgrade', (req, socket, head) => {
  const origin = req.headers.origin;
  if (!ALLOWED_ORIGINS.has(origin)) {
    socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
    socket.destroy();
    return;
  }

  const url = new URL(req.url, 'https://placeholder');
  const ticket = url.searchParams.get('ticket');

  let payload;
  try {
    payload = jwt.verify(ticket, process.env.WS_TICKET_SECRET, { maxAge: '30s' });
  } catch (err) {
    socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
    socket.destroy();
    return;
  }

  wss.handleUpgrade(req, socket, head, (ws) => {
    ws.userId = payload.sub;
    wss.emit('connection', ws, req);
  });
});

Never trust a userId or role sent inside a WebSocket message payload. Once a connection is authenticated at handshake time, attach the verified identity to the server-side connection object (e.g. ws.userId) and use that for every subsequent authorization check — client-supplied fields in message bodies can be forged.

Query-string tokens can end up in reverse-proxy or CDN access logs. If you must pass a token in the URL, make it single-use and short-lived (30-60 seconds), and prefer the Sec-WebSocket-Protocol header where feasible since it isn't logged as part of the request path.

Browsers do not apply same-origin policy to WebSocket handshakes, so servers must validate the Origin header themselves.
Cookies are sent automatically with the WebSocket upgrade request, making cross-origin abuse possible if Origin isn't checked.
Prefer short-lived, single-use tickets over long-lived tokens for the handshake to limit exposure if a token leaks.
Always use wss:// in production; browsers block ws:// from https:// pages via mixed-content rules anyway.
Attach the verified identity to the server-side connection object at handshake time, never trust identity fields in message payloads.
Query-string tokens risk leaking into logs, so keep them short-lived and consider header-based alternatives.