Socket.io JWT Auth

0.2.1 verified Sat Apr 25 auth: no javascript maintenance

Socket.io authentication middleware using JSON Web Tokens (JWT). Current stable version is 0.2.0. This package provides a simple way to authenticate Socket.io connections by verifying a JWT token passed as a query parameter (or auth object for Socket.io v3+). It supports custom secret, algorithm selection, and optional succeedWithoutToken mode for guest connections. The package is designed for Socket.io >= 1.0 and is commonly used to protect WebSocket endpoints. Unlike more modern alternatives like socketio-jwt (which is more actively maintained), socketio-jwt-auth has a simple API but has not seen updates since 2018.

Common errors

error TypeError: jwtAuth.authenticate is not a function ↓

cause CommonJS require incorrectly used as named import or module missing.

fix

Use const jwtAuth = require('socketio-jwt-auth'); then jwtAuth.authenticate(...).

error TokenExpiredError: jwt expired ↓

cause JWT token has expired; not handled by the library.

fix

Generate tokens with a suitable expiration (e.g., '1h') and refresh token logic on client.

error JsonWebTokenError: invalid algorithm ↓

cause Token's algorithm differs from the 'algorithm' option in middleware (default HS256).

fix

Ensure client and server use the same algorithm (e.g., HS256, RS256).

Warnings

breaking Socket.io v3 changed client connection options: use 'auth' instead of 'query' to pass token. ↓

fix Use auth: { token: '...' } instead of query: 'auth_token=...'.

deprecated Package is not actively maintained; last update 2018. Vulnerable dependencies (jsonwebtoken) may cause security issues. ↓

fix Consider migrating to socketio-jwt (if using Socket.io v2) or implementing custom JWT verification.

gotcha If succeedWithoutToken is true, the verify callback payload may be undefined. Not handling this can cause crashes. ↓

fix Always check if payload exists before accessing properties: if (payload && payload.sub) { ... }

gotcha The token must be passed as 'auth_token' in query string, but if query is not provided, middleware passes authentication silently. ↓

fix Always ensure the client sends the token properly via query/auth.

Install

npm install socketio-jwt-auth

yarn add socketio-jwt-auth

pnpm add socketio-jwt-auth

Imports

jwtAuth
wrong
```
import jwtAuth from 'socketio-jwt-auth';
```
correct
```
const jwtAuth = require('socketio-jwt-auth');
```
This package does not ship ES modules; use require(). The default export is an object with an authenticate method.

authenticate

wrong

const { authenticate } = require('socketio-jwt-auth').default;

correct

const { authenticate } = require('socketio-jwt-auth');

No need to access .default; the module exports direct.

io.use(jwtAuth.authenticate)
wrong
```
io.use(jwtAuth.authenticate(options)(verify));
```
correct
```
io.use(jwtAuth.authenticate(options, verify));
```
authenticate returns a middleware function directly. It does not need to be called twice.

Quickstart

Shows how to set up Socket.io server with JWT authentication middleware and client connection with token.

const io = require('socket.io')(3000);
const jwtAuth = require('socketio-jwt-auth');

// Simple middleware that accepts token and attaches user info
io.use(jwtAuth.authenticate({
  secret: 'mySecret',
  algorithm: 'HS256'
}, (payload, done) => {
  // Simulate user lookup
  const user = { id: payload.sub, name: 'John Doe' };
  done(null, user);
}));

io.on('connection', (socket) => {
  console.log('User authenticated:', socket.request.user);
  socket.emit('authenticated', { message: 'Welcome!' });
});

// Client connects with token
const socket = require('socket.io-client')('http://localhost:3000', {
  query: 'auth_token=validJWTToken'
});