Solving WebSocket Authentication: Why Cookies Beat Bearer Tokens

The WebSocket Auth Problem: Cookies vs. Bearer Tokens

Nikhil Sharma addresses the architectural friction of authenticating real-time connections. The native browser WebSocket API does not support custom headers, rendering standard Authorization: Bearer tokens unusable during the initial handshake.

Why This Matters

While REST APIs rely on interceptors to attach JWTs, WebSockets begin with an HTTP GET Upgrade request that ignores custom headers. This creates a gap between the ideal security model (header-based tokens) and technical reality, forcing developers to use insecure query parameters or complex ‘first-message’ authentication logic that increases latency and boilerplate code.

Key Insights

• Bearer Token Limitations: Native browser WebSockets cannot send custom headers, making standard JWT headers impossible during the handshake (Nikhil Sharma, 2026).
• Insecure Workarounds: Using query parameters for tokens leads to sensitive data leaking into server logs and browser histories.
• Native Cookie Integration: Browsers automatically attach associated cookies to the HTTP Upgrade request, allowing for seamless authentication without client-side code changes.
• Backend Requirement: Unlike Express middleware, Node.js IncomingMessage requires manual parsing of the raw cookie header string before accepting a connection.

Working Examples

Utility function to parse raw cookies and verify JWT signatures from an IncomingMessage object.

import cookie from "cookie";
import jwt from "jsonwebtoken";
import type { IncomingMessage } from "http";
import { jwtPayloadSchema } from "../../http/schemas/auth.schema.js";

export function extractUserId(req: IncomingMessage): string | null {
  const cookies = cookie.parse(req.headers.cookie ?? "");
  const token = cookies.token;
  if (!token) return null;
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET as string);
    const parsed = jwtPayloadSchema.safeParse(decoded);
    if (!parsed.success) {
      return null;
    }
    return parsed.data.id;
  } catch {
    return null;
}
}

WebSocket server initialization that rejects unauthenticated connections at the handshake level using a 4001 status code.

import { WebSocketServer, type WebSocket } from "ws";
import type { Server as HttpServer } from "http";
import { extractUserId } from "./handlers/message.handler.js";
import { sockets } from "./store.js";

export function initWebSocketServer(server: HttpServer) {
  const wss = new WebSocketServer({ server });
  wss.on("connection", (ws: WebSocket, request: IncomingMessage) => {
    ws.on("error", console.error);
    const id = extractUserId(request);
    if (!id) {
      ws.close(4001, "Unauthorized");
      return;
    }
sockets.addUser(id, ws);
dconsole.log(`User ${id} connected successfully.`);	ws.on("message", async (data) => {	// handle messages});	ws.on("close", () => {	sockets.removeUserSocket(id, ws);});});}

Practical Applications

• ，Use case: Relay application utilizing HTTP-only cookies to automate authentication during the WebSocket handshake.

Pitfall: Passing tokens via query parameters resulting in sensitive credentials being stored in proxy and server logs.

References:

• https://dev.to/nikhilsharma6/the-websocket-auth-problem-cookies-vs-bearer-tokens-4eel