Thream/socketio-jwt
Archived
2
1
Fork 0
Code Issues Pull Requests Releases Activity

Merge pull request #141 from auth0-community/konrad-readme-unify

Browse Source 
Unified README structure.
This commit is contained in:
Conrad Sopala 2019-01-15 16:45:54 +00:00 committed by GitHub
commit 9158c54573
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 78 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
README.md
View File

@ -1,16 +1,21 @@
# This library is no longer maintained/supported by Auth0
[![Build Status](https://travis-ci.org/auth0/socketio-jwt.svg)](https://travis-ci.org/auth0/socketio-jwt)
# socketio-jwt
<img src="https://img.shields.io/badge/community-driven-brightgreen.svg"/> <br>
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/).
## Installation
This repo is supported and maintained by Community Developers, not Auth0. For more information about different support levels check https://auth0.com/docs/support/matrix .
## Getting started
Chrome extensions are packaged as `.crx` files for distribution but may be loaded "unpacked" for development. For more information on how to load an unpacked extension, see the [Chrome extension docs](https://developer.chrome.com/extensions/getstarted#unpacked).
### Installation
```
npm install socketio-jwt
```
## Example usage
## Usage
```javascript
// set authorization for socket.io
@ -26,7 +31,7 @@ io.sockets
**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')`
__Client side__:
**Client side**
```javascript
var socket = io.connect('http://localhost:9000');
@ -43,9 +48,9 @@ socket.on('connect', function () {
});
```
## One roundtrip
### 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.
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.
```javascript
var io = require("socket.io")(server);
@ -56,14 +61,12 @@ io.set('authorization', socketioJwt.authorize({
secret: 'your secret or public key',
handshake: true
}));
//////////////////////////////
//// With socket.io >= 1.0 ////
io.use(socketioJwt.authorize({
secret: 'your secret or public key',
handshake: true
}));
///////////////////////////////
io.on('connection', function (socket) {
// in socket.io < 1.0
@ -76,7 +79,7 @@ io.on('connection', function (socket) {
For more validation options see [auth0/jsonwebtoken](https://github.com/auth0/node-jsonwebtoken).
__Client side__:
**Client side**
Append the jwt token using query string:
@ -86,9 +89,9 @@ var socket = io.connect('http://localhost:9000', {
});
```
## Handling token expiration
### Handling token expiration
__Server side__:
**Server side**
When you sign the token with an expiration time:
@ -96,9 +99,9 @@ When you sign the token with an expiration time:
var token = jwt.sign(user_profile, jwt_secret, {expiresInMinutes: 60});
```
Your client-side code should handle it as below.
Your client-side code should handle it as below:
__Client side__:
**Client side**
```javascript
socket.on("unauthorized", function(error) {
@ -109,15 +112,15 @@ socket.on("unauthorized", function(error) {
});
```
## Handling invalid token
### Handling invalid token
Token sent by client is invalid.
__Server side__:
**Server side**:
No further configuration needed.
__Client side__:
**Client side**
Add a callback client-side to execute socket disconnect server-side.
@ -131,7 +134,7 @@ socket.on("unauthorized", function(error, callback) {
});
```
__Server side__:
**Server side**
To disconnect socket server-side without client-side callback:
@ -139,15 +142,15 @@ To disconnect socket server-side without client-side callback:
io.sockets.on('connection', socketioJwt.authorize({
secret: 'secret goes here',
// No client-side callback, terminate connection server-side
callback: false
callback: false
}))
```
__Client side__:
**Client side**
Nothing needs to be changed client-side if callback is false.
__Server side__:
**Server side**
To disconnect socket server-side while giving client-side 15 seconds to execute callback:
@ -155,13 +158,13 @@ To disconnect socket server-side while giving client-side 15 seconds to execute
io.sockets.on('connection', socketioJwt.authorize({
secret: 'secret goes here',
// Delay server-side socket disconnect to wait for client-side callback
callback: 15000
callback: 15000
}))
```
Your client-side code should handle it as below.
Your client-side code should handle it as below:
__Client side__:
**Client side**
```javascript
socket.on("unauthorized", function(error, callback) {
@ -173,13 +176,14 @@ socket.on("unauthorized", function(error, callback) {
});
```
## Getting the secret dynamically
You can pass a function instead of an string when configuring secret.
### Getting the secret dynamically
You can pass a function instead of a 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__:
**Server side**
```javascript
var SECRETS = {
@ -196,26 +200,61 @@ io.use(socketioJwt.authorize({
},
handshake: false
}));
```
## Contribute
You are always welcome to open an issue or provide a pull-request!
Feel like contributing to this repo? We're glad to hear that! Before you start contributing please visit our [Contributing Guideline](https://github.com/auth0-community/getting-started/blob/master/CONTRIBUTION.md).
Also check out the unit tests:
```bash
npm test
```
Here you can also find the [PR template](https://github.com/auth0-community/socketio-jwt/blob/master/PULL_REQUEST_TEMPLATE.md) to fill once creating a PR. It will automatically appear once you open a pull request.
## Issue Reporting
## Issues 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.
Spotted a bug or any other kind of issue? We're just humans and we're always waiting for constructive feedback! Check our section on how to [report issues](https://github.com/auth0-community/getting-started/blob/master/CONTRIBUTION.md#issues)!
## Author
Here you can also find the [Issue template](https://github.com/auth0-community/socketio-jwt/blob/master/ISSUE_TEMPLATE.md) to fill once opening a new issue. It will automatically appear once you create an issue.
[Auth0](auth0.com)
## Repo Community
Feel like PRs and issues are not enough? Want to dive into further discussion about the tool? We created topics for each Auth0 Community repo so that you can join discussion on stack available on our repos. Here it is for this one: [socketio-jwt](https://community.auth0.com/t/auth0-community-oss-socketio-jwt/20024)
<a href="https://community.auth0.com/">
<img src="/assets/join_auth0_community_badge.png"/>
</a>
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
This project is licensed under the MIT license. See the [LICENSE](https://github.com/auth0-community/socketio-jwt/blob/master/LICENSE) file for more info.
## What is Auth0?
Auth0 helps you to:
* Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like
* Google
* Facebook
* Microsoft
* Linkedin
* GitHub
* Twitter
* Box
* Salesforce
* etc.
**or** enterprise identity systems like:
* Windows Azure AD
* Google Apps
* Active Directory
* ADFS
* Any SAML Identity Provider
* Add authentication through more traditional [username/password databases](https://docs.auth0.com/mysql-connection-tutorial)
* Add support for [linking different user accounts](https://docs.auth0.com/link-accounts) with the same user
* Support for generating signed [JSON Web Tokens](https://docs.auth0.com/jwt) to call your APIs and create user identity flow securely
* Analytics of how, when and where users are logging in
* Pull data from other sources and add it to user profile, through [JavaScript rules](https://docs.auth0.com/rules)
## Create a free Auth0 account
* Go to [Auth0 website](https://auth0.com/signup)
* Hit the **SIGN UP** button in the upper-right corner

BIN
assets/join_auth0_community_badge.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB