Notorious Penguin Magicians

    socketio-jwt-auth
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/socketio-jwt-auth package

    0.2.1 • Public • Published

    SocketIO JWT Auth

    Travis Coveralls github npm GitHub license

    Socket.io authentication middleware using Json Web Token

    Work with socket.io >= 1.0

    Installation

    npm install socketio-jwt-auth
    

    Usage

    Register the middleware with socket.io

    socketio-jwt-auth has only one method authenticate(options, verify).

    options is an object literal that contains options:

    • secret a secret key,
    • algorithm, defaults to HS256, and
    • succeedWithoutToken, which, if true tells the middleware not to fail if no token is suppled. Defaults tofalse.

    verify is a function with two args payload, and done:

    • payload is the decoded JWT payload, and
    • done is an error-first callback with three args: done(err, user, message)
    var io = require('socket.io')();
    var jwtAuth = require('socketio-jwt-auth');
     
    // using middleware
    io.use(jwtAuth.authenticate({
      secret: 'Your Secret',    // required, used to verify the token's signature
      algorithm: 'HS256'        // optional, default to be HS256
    }, function(payload, done) {
      // done is a callback, you can use it as follows
      User.findOne({id: payload.sub}, function(err, user) {
        if (err) {
          // return error
          return done(err);
        }
        if (!user) {
          // return fail with an error message
          return done(null, false, 'user does not exist');
        }
        // return success with a user info
        return done(null, user);
      });
    }));

    Connecting without a token

    There are times when you might wish to successfully connect the socket but indentify the connection as being un-authenticated. For example when a user connects as a guest, before supplying login credentials. In this case you must supply the option succeedWithoutToken, as follows:

    var io = require('socket.io')();
    var jwtAuth = require('socketio-jwt-auth');
     
    // using middleware
    io.use(jwtAuth.authenticate({
      secret: 'Your Secret',    // required, used to verify the token's signature
      algorithm: 'HS256',        // optional, default to be HS256
      succeedWithoutToken: true
    }, function(payload, done) {
      // you done callback will not include any payload data now
      // if no token was supplied
      if (payload && payload.sub) {
        User.findOne({id: payload.sub}, function(err, user) {
          if (err) {
            // return error
            return done(err);
          }
          if (!user) {
            // return fail with an error message
            return done(null, false, 'user does not exist');
          }
          // return success with a user info
          return done(null, user);
        });
      } else {
        return done() // in your connection handler user.logged_in will be false
      }
    }));

    Access user info

    io.on('connection', function(socket) {
      console.log('Authentication passed!');
      // now you can access user info through socket.request.user
      // socket.request.user.logged_in will be set to true if the user was authenticated
      socket.emit('success', {
        message: 'success logged in!',
        user: socket.request.user
      });
    });
     
    io.listen(9000);

    Client Side

    <script>
      // You should add auth_token to the query when connecting
      // Replace THE_JWT_TOKEN with the valid one
      var socket = io('http://localhost:9000', {query: 'auth_token=THE_JWT_TOKEN'});
      // For socket.io v3 you must use 'auth' object in place of 'query'
      // var socket = io('http://localhost:9000', {auth: 'auth_token=THE_JWT_TOKEN'});
      // Connection failed
      socket.on('error', function(err) {
        throw new Error(err);
      });
      // Connection succeeded
      socket.on('success', function(data) {
        console.log(data.message);
        console.log('user info: ' + data.user);
        console.log('logged in: ' + data.user.logged_in)
      })
    </script>

    If your client support, you can also choose to pass the auth token in headers.

    <script>
      // Use extraHeaders to set a custom header, the key is 'x-auth-token'.
      // Don't forget to replace THE_JWT_TOKEN with the valid one.
      var socket = io('http://localhost:9000', {
        extraHeaders: {
          'x-auth-token': 'THE_JWT_TOKEN'
        },
        transportOptions: {
          polling: {
            extraHeaders: {
              'x-auth-token': 'THE_JWT_TOKEN'
            }
          }
        },
      });
      // ...
    </script>

    Tests

    npm install
    npm test
    

    Change Log

    0.2.1

    • Fix a bug caused by undefined

    0.2.0

    • Add auth handshake for Socket.IO v3

    0.1.0

    • Add support for passing auth token with extraHeaders

    0.0.6

    • Fix an api bug of node-simple-jwt

    0.0.5

    • Add an option (succeedWithoutToken) to allow guest connection

    License

    The MIT License

    Copyright (c) 2015 Lei Lei

    Install

    npm i socketio-jwt-auth

    DownloadsWeekly Downloads

    2,184

    Version

    0.2.1

    License

    MIT

    Unpacked Size

    15.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar