Registry / auth-security / socketio-jwt-auth

socketio-jwt-auth

JSON →
library0.2.1jsnpmunverified

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.

auth-securityhttp-networkingweb-framework
npm install socketio-jwt-auth
github ↗package ↗
INSTALL
IMPORT
SIG · SOCKETIO-JWT-AUTH
S
socketio-jwt-auth
auth-securityjavascriptv0.2.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

jwtAuth
✓ const jwtAuth = require('socketio-jwt-auth');
✗ import jwtAuth from 'socketio-jwt-auth';
This package does not ship ES modules; use require(). The default export is an object with an authenticate method.
authenticate
✓ const { authenticate } = require('socketio-jwt-auth');
✗ const { authenticate } = require('socketio-jwt-auth').default;
No need to access .default; the module exports direct.
io.use(jwtAuth.authenticate)
✓ io.use(jwtAuth.authenticate(options, verify));
✗ io.use(jwtAuth.authenticate(options)(verify));
authenticate returns a middleware function directly. It does not need to be called twice.

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' });
Debug
Known issues
breakingSocket.io v3 changed client connection options: use 'auth' instead of 'query' to pass token.
fix
Use auth: { token: '...' } instead of query: 'auth_token=...'.
affects: >=3.0.0
deprecatedPackage 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.
affects: *
gotchaIf 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) { ... }
affects: *
gotchaThe 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.
affects: *
Errors
Common errors & fixes
TypeError: jwtAuth.authenticate is not a function
CommonJS require incorrectly used as named import or module missing.
fix
Use const jwtAuth = require('socketio-jwt-auth'); then jwtAuth.authenticate(...).
TokenExpiredError: jwt expired
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.
JsonWebTokenError: invalid algorithm
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).
Upgrade
Version history
0.2.1latest on npm
Audit
Dependencies
jsonwebtokenrequiredUsed to decode and verify JWT tokens
socket.iorequiredPeer dependency - the middleware is designed for Socket.io
Agent activity
21 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/adcentury/socketio-jwt-auth ↗
packagehttps://www.npmjs.com/package/socketio-jwt-auth ↗
socketio-jwt-auth — npm install socketio-jwt-auth · libregistry