Skip to content
This repository has been archived by the owner. It is now read-only.
Authentication module for socket.io
Branch: development
Clone or download
Latest commit 4efe80f Aug 7, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Update socketio-auth.js May 11, 2018
test add unit test for disconnect configuration option Oct 20, 2016
.editorconfig Add jshint/jscs and fix styles. May 11, 2015
.gitignore Initial commit Oct 15, 2014
.jscsrc Add jshint/jscs and fix styles. May 11, 2015
.jshintrc Add jshint/jscs and fix styles. May 11, 2015
.travis.yml Add travis. May 11, 2015
README.md Update README.md Aug 7, 2018
index.js initial commit Oct 15, 2014
package.json 0.1.1 May 14, 2018

README.md

socketio-auth Build Status

This module provides hooks to implement authentication in socket.io without using querystrings to send credentials, which is not a good security practice.

NOTE: I'm not maintaining this project anymore. I don't use socket.io so I can't tell if it's still useful.

Client:

var socket = io.connect('http://localhost');
socket.on('connect', function(){
  socket.emit('authentication', {username: "John", password: "secret"});
  socket.on('authenticated', function() {
    // use the socket as usual
  });
});

Server:

var io = require('socket.io').listen(app);

require('socketio-auth')(io, {
  authenticate: function (socket, data, callback) {
    //get credentials sent by the client
    var username = data.username;
    var password = data.password;

    db.findUser('User', {username:username}, function(err, user) {

      //inform the callback of auth success/failure
      if (err || !user) return callback(new Error("User not found"));
      return callback(null, user.password == password);
    });
  }
});

The client should send an authentication event right after connecting, including whatever credentials are needed by the server to identify the user (i.e. user/password, auth token, etc.). The authenticate function receives those same credentials in 'data', and the actual 'socket' in case header information like the origin domain is important, and uses them to authenticate.

Configuration

To setup authentication for the socket.io connections, just pass the server socket to socketio-auth with a configuration object:

var io = require('socket.io').listen(app);

require('socketio-auth')(io, {
  authenticate: authenticate,
  postAuthenticate: postAuthenticate,
  disconnect: disconnect,
  timeout: 1000
});

The supported parameters are:

  • authenticate: The only required parameter. It's a function that takes the data sent by the client and calls a callback indicating if authentication was successfull:
function authenticate(socket, data, callback) {
  var username = data.username;
  var password = data.password;

  db.findUser('User', {username:username}, function(err, user) {
    if (err || !user) return callback(new Error("User not found"));
    return callback(null, user.password == password);
  });
}
  • postAuthenticate: a function to be called after the client is authenticated. It's useful to keep track of the user associated with a client socket:
function postAuthenticate(socket, data) {
  var username = data.username;

  db.findUser('User', {username:username}, function(err, user) {
    socket.client.user = user;
  });
}
  • disconnect: a function to be called after the client is disconnected.
function disconnect(socket) {
  console.log(socket.id + ' disconnected');
}
  • timeout: The amount of millisenconds to wait for a client to authenticate before disconnecting it. Defaults to 1000. The value 'none' disables the timeout feature.

Auth error messages

When client authentication fails, the server will emit an unauthorized event with the failure reason:

socket.emit('authentication', {username: "John", password: "secret"});
socket.on('unauthorized', function(err){
  console.log("There was an error with the authentication:", err.message);
});

The value of err.message depends on the outcome of the authenticate function used in the server: if the callback receives an error its message is used, if the success parameter is false the message is 'Authentication failure'

function authenticate(socket, data, callback) {
  db.findUser('User', {username:data.username}, function(err, user) {
    if (err || !user) {
      //err.message will be "User not found"
      return callback(new Error("User not found"));
    }

    //if wrong password err.message will be "Authentication failure"
    return callback(null, user.password == data.password);
  });
}

After receiving the unauthorized event, the client is disconnected.

Implementation details

socketio-auth implements two-step authentication: upon connection, the server marks the clients as unauthenticated and listens to an authentication event. If a client provides wrong credentials or doesn't authenticate after a timeout period it gets disconnected. While the server waits for a connected client to authenticate, it won't emit any broadcast/namespace events to it. By using this approach the sensitive authentication data, such as user credentials or tokens, travel in the body of a secure request, rather than a querystring that can be logged or cached.

Note that during the window while the server waits for authentication, direct messages emitted to the socket (i.e. socket.emit(msg)) will be received by the client. To avoid those types of messages reaching unauthorized clients, the emission code should either be defined after the authenticated event is triggered by the server or the socket.auth flag should be checked to make sure the socket is authenticated.

See this blog post for more details on this authentication method.

You can’t perform that action at this time.