Repository files navigation

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

Client:

varsocket=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:

vario=require('socket.io').listen(app);require('socketio-auth')(io,{authenticate:function(socket,data,callback){//get credentials sent by the clientvarusername=data.username;varpassword=data.password;db.findUser('User',{username:username},function(err,user){//inform the callback of auth success/failureif(err||!user)returncallback(newError("User not found"));returncallback(null,user.password==password);}}});

The client should send anauthentication event right after connecting, including whatever credentials are needed by the server to identify the user (i.e. user/password, auth token, etc.). Theauthenticate 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.

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

vario=require('socket.io').listen(app);require('socketio-auth')(io,{authenticate:authenticate,postAuthenticate:postAuthenticate,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:

functionauthenticate(socket,data,callback){varusername=data.username;varpassword=data.password;db.findUser('User',{username:username},function(err,user){if(err||!user)returncallback(newError("User not found"));returncallback(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:

functionpostAuthenticate(socket,data){varusername=data.username;db.findUser('User',{username:username},function(err,user){socket.client.user=user;}}

• 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.

When client authentication fails, the server will emit anunauthorized 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 oferr.message depends on the outcome of theauthenticate 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'

functionauthenticate(socket,data,callback){db.findUser('User',{username:data.username},function(err,user){if(err||!user){//err.message will be "User not found"returncallback(newError("User not found"));}//if wrong password err.message will be "Authentication failure"returncallback(null,user.password==data.password);}}

After receiving theunauthorized event, the client is disconnected.

socketio-auth implements two-step authentication: upon connection, the server marks the clients as unauthenticated and listens to anauthentication 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 theauthenticated event is triggered by the server or thesocket.auth flag should be checked to make sure the socket is authenticated.

Seethis blog post for more details on this authentication method.