A real-time application should not allow every visitor to perform protected actions.

For example, consider a private messaging application. Users should only be allowed to:

• Connect with a valid identity.
• Join rooms they have permission to access.
• Send messages as their authenticated account.
• Receive private notifications intended for them.

Socket.IO provides middleware through io.use().

This middleware runs during the connection process, before the connection is fully established.

The client can provide authentication data through the auth option.

For example:

const socket = io({
  auth: {
    token: accessToken
  }
});

On the server, this value can be accessed through socket.handshake.auth.

The server must verify the token rather than trusting the value supplied by the browser.

We will use the jsonwebtoken package to demonstrate JWT verification.

Install it using npm.

The package provides methods for signing and verifying JSON Web Tokens.

This tutorial focuses on verifying tokens issued by an existing authentication system. In a real application, token issuance should be handled by your established authentication service.

npm install jsonwebtoken

Create src/middleware/socket-auth.js.

The middleware should:

1. Read the token from the handshake authentication payload.
2. Reject missing credentials.
3. Verify the JWT signature.
4. Validate important claims such as expiration and subject.
5. Store the verified identity inside socket.data.
6. Allow the connection to continue.

The socket.data object is useful for storing information associated with the current connection.

import jwt from 'jsonwebtoken';

export function socketAuth(socket, next) {
  const token = socket.handshake.auth?.token;

  if (typeof token !== 'string' || token.length === 0) {
    return next(new Error('Authentication required'));
  }

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'],
      issuer: 'chat-api',
      audience: 'chat-client'
    });

    if (
      typeof payload !== 'object' ||
      typeof payload.sub !== 'string' ||
      payload.sub.length === 0
    ) {
      return next(new Error('Invalid user identity'));
    }

    socket.data.userId = payload.sub;
    next();
  } catch (error) {
    next(new Error('Invalid or expired authentication token'));
  }
}

Now register the authentication middleware in src/config/socket.js.

Socket.IO allows middleware to be registered using io.use().

After registration, connections without valid tokens will be rejected.

import { Server } from 'socket.io';
import { socketAuth } from '../middleware/socket-auth.js';

export function initializeSocket(httpServer) {
  const io = new Server(httpServer);

  io.use(socketAuth);

  return io;
}

The browser must provide an access token when establishing the Socket.IO connection.

For demonstration purposes, assume the application already has an access token issued by a trusted login system.

The token can be passed through the Socket.IO auth configuration.

Do not generate trusted user identities using values supplied through ordinary form fields.

const accessToken = window.localStorage.getItem('accessToken');

const socket = io({
  auth: {
    token: accessToken
  }
});

socket.on('connect', () => {
  console.log('Authenticated socket connected');
});

socket.on('connect_error', (error) => {
  console.error('Connection rejected:', error.message);
});

After authentication, do not trust the username or user ID provided by the browser for protected actions.

Use the identity stored in socket.data.userId.

For example, when a user sends a chat message, the backend should determine the sender from the authenticated connection.

This prevents clients from pretending to be another user by changing the username in the event payload.

io.on('connection', (socket) => {
  socket.on('chat:send', (payload, acknowledge) => {
    const userId = socket.data.userId;
    const message = payload?.message;

    if (
      typeof message !== 'string' ||
      message.trim().length === 0 ||
      message.length > 1000
    ) {
      acknowledge?.({
        success: false,
        error: 'Invalid message'
      });
      return;
    }

    const chatMessage = {
      senderId: userId,
      message: message.trim(),
      timestamp: new Date().toISOString()
    };

    io.emit('chat:message', chatMessage);

    acknowledge?.({ success: true });
  });
});

A room name should never be treated as proof of authorization.

For example, a user should not be allowed to join a private project room simply by sending:

socket.emit('room:join', {
  room: 'confidential-project'
});

The backend must check whether the authenticated user belongs to that project.

A typical authorization workflow is:

1. Receive the requested room identifier.
2. Read the authenticated user ID from socket.data.
3. Query the database or authorization service.
4. Verify membership and access permissions.
5. Join the room only after authorization succeeds.
6. Return an acknowledgement.

socket.on('project:join', async (payload, acknowledge) => {
  try {
    const projectId = payload?.projectId;
    const userId = socket.data.userId;

    if (typeof projectId !== 'string') {
      acknowledge?.({ success: false, error: 'Invalid project' });
      return;
    }

    // Replace this function with a real database membership check.
    const isMember = await projectService.isMember(userId, projectId);

    if (!isMember) {
      acknowledge?.({ success: false, error: 'Access denied' });
      return;
    }

    await socket.join(`project:${projectId}`);

    acknowledge?.({ success: true });
  } catch (error) {
    console.error('Project authorization failed:', error);

    acknowledge?.({
      success: false,
      error: 'Unable to join project'
    });
  }
});