2
1
mirror of https://github.com/Thream/socketio-jwt.git synced 2024-07-21 09:38:31 +02:00
socketio-jwt/README.md

222 lines
5.8 KiB
Markdown
Raw Normal View History

2017-08-31 20:53:25 +02:00
# This library is no longer maintained/supported by Auth0
2017-08-31 19:54:21 +02:00
2015-05-29 14:42:14 +02:00
[![Build Status](https://travis-ci.org/auth0/socketio-jwt.svg)](https://travis-ci.org/auth0/socketio-jwt)
Authenticate socket.io 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](http://blog.auth0.com/2014/01/07/angularjs-authentication-with-cookies-vs-token/).
2012-09-05 20:14:36 +02:00
2013-11-15 15:16:16 +01:00
## Installation
2012-09-05 20:14:36 +02:00
```
npm install socketio-jwt
2012-09-05 20:14:36 +02:00
```
2013-11-15 15:16:16 +01:00
## Example usage
2012-09-05 20:14:36 +02:00
2014-01-14 12:30:39 +01:00
```javascript
// set authorization for socket.io
io.sockets
.on('connection', socketioJwt.authorize({
secret: 'your secret or public key',
timeout: 15000 // 15 seconds to send the authentication message
2014-03-25 13:11:39 +01:00
})).on('authenticated', function(socket) {
2014-01-14 12:30:39 +01:00
//this socket is authenticated, we are good to handle more events from it.
console.log('hello! ' + socket.decoded_token.name);
2015-05-29 14:49:24 +02:00
});
2014-01-14 12:30:39 +01:00
```
**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')`
2014-01-14 12:30:39 +01:00
__Client side__:
```javascript
var socket = io.connect('http://localhost:9000');
2016-08-19 17:01:36 +02:00
socket.on('connect', function () {
2014-01-14 12:30:39 +01:00
socket
2016-08-19 17:01:36 +02:00
.emit('authenticate', {token: jwt}) //send the jwt
2014-01-14 12:30:39 +01:00
.on('authenticated', function () {
//do other things
})
2016-08-19 17:01:36 +02:00
.on('unauthorized', function(msg) {
console.log("unauthorized: " + JSON.stringify(msg.data));
throw new Error(msg.data.type);
})
2014-01-14 12:30:39 +01:00
});
```
## One roundtrip
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.
2012-09-05 20:14:36 +02:00
```javascript
var io = require("socket.io")(server);
var socketioJwt = require("socketio-jwt");
2012-09-05 20:14:36 +02:00
2014-06-03 13:12:07 +02:00
//// With socket.io < 1.0 ////
io.set('authorization', socketioJwt.authorize({
2014-01-14 12:30:39 +01:00
secret: 'your secret or public key',
handshake: true
}));
2014-06-03 13:12:07 +02:00
//////////////////////////////
//// With socket.io >= 1.0 ////
io.use(socketioJwt.authorize({
secret: 'your secret or public key',
handshake: true
}));
///////////////////////////////
2014-01-13 22:41:10 +01:00
io.on('connection', function (socket) {
2014-06-09 15:51:40 +02:00
// in socket.io < 1.0
console.log('hello!', socket.handshake.decoded_token.name);
2014-06-12 18:23:19 +02:00
2014-06-09 15:51:40 +02:00
// in socket.io 1.0
2014-06-12 18:23:19 +02:00
console.log('hello! ', socket.decoded_token.name);
2014-01-13 22:41:10 +01:00
})
2013-11-15 15:16:16 +01:00
```
2012-11-16 16:43:12 +01:00
For more validation options see [auth0/jsonwebtoken](https://github.com/auth0/node-jsonwebtoken).
2012-11-16 16:43:12 +01:00
__Client side__:
2013-11-15 15:16:16 +01:00
2014-01-13 22:41:10 +01:00
Append the jwt token using query string:
2013-11-19 10:52:36 +01:00
```javascript
var socket = io.connect('http://localhost:9000', {
'query': 'token=' + your_jwt
2013-11-19 10:52:36 +01:00
});
```
## Handling token expiration
__Server side__:
When you sign the token with an expiration time:
```javascript
var token = jwt.sign(user_profile, jwt_secret, {expiresInMinutes: 60});
```
Your client-side code should handle it as below.
__Client side__:
```javascript
socket.on("unauthorized", function(error) {
if (error.data.type == "UnauthorizedError" || error.data.code == "invalid_token") {
// redirect user to login page perhaps?
console.log("User's token has expired");
}
});
```
## Handling invalid token
Token sent by client is invalid.
__Server side__:
No further configuration needed.
__Client side__:
Add a callback client-side to execute socket disconnect server-side.
```javascript
socket.on("unauthorized", function(error, callback) {
if (error.data.type == "UnauthorizedError" || error.data.code == "invalid_token") {
// redirect user to login page perhaps or execute callback:
callback();
console.log("User's token has expired");
}
});
```
__Server side__:
To disconnect socket server-side without client-side callback:
```javascript
io.sockets.on('connection', socketioJwt.authorize({
secret: 'secret goes here',
// No client-side callback, terminate connection server-side
callback: false
}))
```
__Client side__:
Nothing needs to be changed client-side if callback is false.
__Server side__:
To disconnect socket server-side while giving client-side 15 seconds to execute callback:
```javascript
io.sockets.on('connection', socketioJwt.authorize({
secret: 'secret goes here',
// Delay server-side socket disconnect to wait for client-side callback
callback: 15000
}))
```
Your client-side code should handle it as below.
__Client side__:
```javascript
socket.on("unauthorized", function(error, callback) {
if (error.data.type == "UnauthorizedError" || error.data.code == "invalid_token") {
// redirect user to login page perhaps or execute callback:
callback();
console.log("User's token has expired");
}
});
```
## Getting the secret dynamically
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__:
```javascript
var SECRETS = {
'user1': 'secret 1',
'user2': 'secret 2'
}
io.use(socketioJwt.authorize({
secret: function(request, decodedToken, callback) {
// SECRETS[decodedToken.userId] will be used a a secret or
// public key for connection user.
callback(null, SECRETS[decodedToken.userId]);
},
handshake: false
}));
```
## Contribute
2013-11-19 10:52:36 +01:00
You are always welcome to open an issue or provide a pull-request!
2013-11-15 15:16:16 +01:00
Also check out the unit tests:
```bash
npm test
```
2012-09-05 20:14:36 +02:00
2016-01-14 13:19:40 +01:00
## Issue Reporting
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](https://auth0.com/whitehat) details the procedure for disclosing security issues.
## Author
[Auth0](auth0.com)
2013-11-15 15:16:16 +01:00
## License
2016-01-14 13:19:40 +01:00
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.