{"id":18809,"library":"socketio-jwt-auth","title":"Socket.io JWT Auth","description":"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.","status":"maintenance","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/adcentury/socketio-jwt-auth","tags":["javascript","socket.io","socket.io middleware","authenticate","authentication","authorize","authorization","auth","jwt"],"install":[{"cmd":"npm install socketio-jwt-auth","lang":"bash","label":"npm"},{"cmd":"yarn add socketio-jwt-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add socketio-jwt-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used to decode and verify JWT tokens","package":"jsonwebtoken","optional":false},{"reason":"Peer dependency - the middleware is designed for Socket.io","package":"socket.io","optional":false}],"imports":[{"note":"This package does not ship ES modules; use require(). The default export is an object with an authenticate method.","wrong":"import jwtAuth from 'socketio-jwt-auth';","symbol":"jwtAuth","correct":"const jwtAuth = require('socketio-jwt-auth');"},{"note":"No need to access .default; the module exports direct.","wrong":"const { authenticate } = require('socketio-jwt-auth').default;","symbol":"authenticate","correct":"const { authenticate } = require('socketio-jwt-auth');"},{"note":"authenticate returns a middleware function directly. It does not need to be called twice.","wrong":"io.use(jwtAuth.authenticate(options)(verify));","symbol":"io.use(jwtAuth.authenticate)","correct":"io.use(jwtAuth.authenticate(options, verify));"}],"quickstart":{"code":"const io = require('socket.io')(3000);\nconst jwtAuth = require('socketio-jwt-auth');\n\n// Simple middleware that accepts token and attaches user info\nio.use(jwtAuth.authenticate({\n  secret: 'mySecret',\n  algorithm: 'HS256'\n}, (payload, done) => {\n  // Simulate user lookup\n  const user = { id: payload.sub, name: 'John Doe' };\n  done(null, user);\n}));\n\nio.on('connection', (socket) => {\n  console.log('User authenticated:', socket.request.user);\n  socket.emit('authenticated', { message: 'Welcome!' });\n});\n\n// Client connects with token\nconst socket = require('socket.io-client')('http://localhost:3000', {\n  query: 'auth_token=validJWTToken'\n});","lang":"javascript","description":"Shows how to set up Socket.io server with JWT authentication middleware and client connection with token."},"warnings":[{"fix":"Use auth: { token: '...' } instead of query: 'auth_token=...'.","message":"Socket.io v3 changed client connection options: use 'auth' instead of 'query' to pass token.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consider migrating to socketio-jwt (if using Socket.io v2) or implementing custom JWT verification.","message":"Package is not actively maintained; last update 2018. Vulnerable dependencies (jsonwebtoken) may cause security issues.","severity":"deprecated","affected_versions":"*"},{"fix":"Always check if payload exists before accessing properties: if (payload && payload.sub) { ... }","message":"If succeedWithoutToken is true, the verify callback payload may be undefined. Not handling this can cause crashes.","severity":"gotcha","affected_versions":"*"},{"fix":"Always ensure the client sends the token properly via query/auth.","message":"The token must be passed as 'auth_token' in query string, but if query is not provided, middleware passes authentication silently.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use const jwtAuth = require('socketio-jwt-auth'); then jwtAuth.authenticate(...).","cause":"CommonJS require incorrectly used as named import or module missing.","error":"TypeError: jwtAuth.authenticate is not a function"},{"fix":"Generate tokens with a suitable expiration (e.g., '1h') and refresh token logic on client.","cause":"JWT token has expired; not handled by the library.","error":"TokenExpiredError: jwt expired"},{"fix":"Ensure client and server use the same algorithm (e.g., HS256, RS256).","cause":"Token's algorithm differs from the 'algorithm' option in middleware (default HS256).","error":"JsonWebTokenError: invalid algorithm"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}