passport.socketio
Access passport.js user information from a socket.io connection.
Installation
npm install passport.socketio
Example usage
// initialize our modulesvar io = server sessionStore = // find a working session store (have a look at the readme) passportSocketIo = ; // With Socket.io < 1.0io; //With Socket.io >= 1.0io; { console; // The accept-callback still allows us to decide whether to // accept the connection or not. ; // OR // If you use socket.io@1.X the callback looks different ;} { iferror throw message; console; // We use this callback to log all of our failed connections. ; // OR // If you use socket.io@1.X the callback looks different // If you don't want to accept the connection iferror ; // this error will be sent to the user as a special error-package // see: http://socket.io/docs/client-api/#socket > error-object}
passport.socketio - Options
store
[function] required:
Always provide one. If you don't know what sessionStore to use, have a look at this list.
Also be sure to use the same sessionStore or at least a connection to the same collection/table/whatever. And don't forget your express.session()
middleware:
app.use(express.session({ store: awesomeSessionStore }));
For further info about this middleware see the official documentation.
You can also check the simple example below using a redis store.
//in your app.jsvar sessionStore = ; app; //in your passport.socketio setup//With Socket.io >= 1.0 (you will have the same setup for Socket.io <1)io;
cookieParser
[function] optional:
Optional cookieParser from express. Express 3 is express.cookieParser
in Express 4 require('cookie-parser')
.
Defaults to require('cookie-parser')
.
key
[string] optional:
Defaults to 'connect.sid'
. But you're always better of to be sure and set your own key. Don't forget to also change it in your express.session()
:
app.use(express.session({ key: 'your.sid-key' }));
secret
[string] optional:
As with key
, also the secret you provide is optional. But: be sure to have one. That's always safer. You can set it like the key:
app.use(express.session({ secret: 'pinkie ate my cupcakes!' }));
passport
[function] optional:
Defaults to require('passport')
. If you want, you can provide your own instance of passport for whatever reason.
success
[function] optional:
Callback which will be called everytime a authorized user successfuly connects to your socket.io instance. Always be sure to accept/reject the connection.
For that, there are two parameters: function(data[object], accept[function])
. data
contains all the user-information from passport.
The second parameter is for accepting/rejecting connections. Use it like this if you use socket.io under 1.0:
// accept connection; // reject connection (for whatever reason);
And like this if you use the newest version of socket.io@1.X
// accept connection; // reject connection (for whatever reason);
fail
[function] optional:
The name of this callback may be a little confusing. While it is called when a not-authorized-user connects, it is also called when there's a error.
For debugging reasons you are provided with two additional parameters function(data[object], message[string], error[bool], accept[function])
: (socket.io @ < 1.X)
/* ... */{ // error indicates whether the fail is due to an error or just a unauthorized client iferror throw message; else console; // the same accept-method as above in the success-callback ; } // or// This function accepts every client unless there's an error{ console; ;}
Socket.io@1.X:
{ // error indicates whether the fail is due to an error or just a unauthorized client iferror throw message; // send the (not-fatal) error-message to the client and deny the connection return ;} // or// This function accepts every client unless there's an critical error{ iferror throw message; return ;}
You can use the message
parameter for debugging/logging/etc uses.
socket.handshake.user
(prior to v1)
This property was removed in v1. See socket.request.user
socket.request.user
(as of v1)
This property is always available from inside a io.on('connection')
handler. If the user is authorized via passport, you can access all the properties from there.
Plus you have the socket.request.user.logged_in
property which tells you whether the user is currently authorized or not.
Note: This property was named socket.handshake.user prior to v1
Additional methods
passportSocketIo.filterSocketsByUser
This function gives you the ability to filter all connected sockets via a user property. Needs two parameters function(io, function(user))
. Example:
passportSocketIo;
CORS-Workaround:
If you happen to have to work with Cross-Origin-Requests (marked by socket.io v0.9 as handshake.xdomain
and by socket.io v1.0 as request.xdomain
) then here's a workaround:
Clientside:
You have to provide the session-cookie. If you haven't set a name yet, do it like this: app.use(express.session({ key: 'your.sid-key' }));
// Note: ther's no readCookie-function built in.// Get your own in the internetzsocket = io;
Serverside:
Nope, there's nothing to do on the server side. Just be sure that the cookies names match.
Notes:
- Does NOT support cookie-based sessions. eg:
express.cookieSession
- If the connection fails, check if you are requesting from a client via CORS. Check
socket.handshake.xdomain === true
(socket.request.xdomain === true
with socket.io v1) as there are no cookies sent. For a workaround look at the code above.
Contribute
You are always welcome to open an issue or provide a pull-request! Also check out the unit tests:
npm test
License
Licensed under the MIT-License. 2012-2013 José F. Romaniello.