authenticate connections using JWTs

Authenticate incoming connections with JWTs. This is useful if you are build a single page application and you are not using cookies as explained in this blog post: Cookies vs Tokens. Getting auth right with Angular.JS.

npm install socketio-jwt
// set authorization for 
  .on('connection', socketioJwt.authorize({
    secret: 'your secret or public key',
    timeout: 15000 // 15 seconds to send the authentication message 
  })).on('authenticated', function(socket) {
    //this socket is authenticated, we are good to handle more events from it. 
    console.log('hello! ' +;

Note: If you are using a base64-encoded secret (e.g. your Auth0 secret key), you need to convert it to a Buffer: Buffer('your secret key', 'base64')

Client side:

var socket = io.connect('http://localhost:9000');
socket.on('connect', function (socket) {
    .on('authenticated', function () {
      //do other things 
    .emit('authenticate', {token: jwt}); //send the jwt 

The previous approach uses a second roundtrip to send the jwt, there is a way you can authenticate on the handshake by sending the JWT as a query string, the caveat is that intermediary HTTP servers can log the url.

var io            = require("")(server);
var socketioJwt   = require("socketio-jwt");
//// With < 1.0 //// 
io.set('authorization', socketioJwt.authorize({
  secret: 'your secret or public key',
  handshake: true
//// With >= 1.0 //// 
  secret: 'your secret or public key',
  handshake: true
io.on('connection', function (socket) {
  // in < 1.0 
  // in 1.0 
  console.log('hello! ',;

For more validation options see auth0/jsonwebtoken.

Client side:

Append the jwt token using query string:

var socket = io.connect('http://localhost:9000', {
  'query': 'token=' + your_jwt

Server side:

When you sign the token with an expiration time:

var token = jwt.sign(user_profile, jwt_secret, {expiresInMinutes: 60});

Your client-side code should handle it as below.

Client side:

socket.on("error", function(error) {
  if (error.type == "UnauthorizedError" || error.code == "invalid_token") {
    // redirect user to login page perhaps? 
    console.log("User's token has expired");

You can pass a function instead of an string when configuring secret. This function receives the request, the decoded token and a callback. This way, you are allowed to use a different secret based on the request and / or the provided token.

Server side:

var SECRETS = {
  'user1': 'secret 1',
  'user2': 'secret 2'
  secretfunction(requestdecodedTokencallback) {
    // SECRETS[decodedToken.userId] will be used a a secret or 
    // public key for connection user. 
    callback(null, SECRETS[decodedToken.userId]);
  handshake: false

You are always welcome to open an issue or provide a pull-request!

Also check out the unit tests:

npm test

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.


This project is licensed under the MIT license. See the LICENSE file for more info.