Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/paddingme/express-jwt-blacklist

express-jwt plugin for token blacklisting
https://github.com/paddingme/express-jwt-blacklist

Last synced: about 10 hours ago
JSON representation

express-jwt plugin for token blacklisting

Awesome Lists containing this project

README 

        
# express-jwt-blacklist

[![Build Status](http://img.shields.io/travis/layerhq/express-jwt-blacklist.svg)](https://travis-ci.org/layerhq/express-jwt-blacklist)

[![npm version](http://img.shields.io/npm/v/express-jwt-blacklist.svg)](https://npmjs.org/package/express-jwt-blacklist) 



A library designed to be a complementary plugin for [express-jwt](https://github.com/auth0/express-jwt) middleware.



## Simple example



```javascript

var express = require('express');

var jwt = require('express-jwt');

var blacklist = require('express-jwt-blacklist');

var app = express();



app.use(jwt({

  secret: 'my-secret',

  isRevoked: blacklist.isRevoked

}));



app.get('/logout', function (req, res) {

  blacklist.revoke(req.user)

  res.sendStatus(200);

});



var server = app.listen(3000);

```



## Installation



    npm install express-jwt-blacklist



## Usage



By default in-memory cache is used to store blacklist data. I do **not** recommend using this in production and especially if you are dealing with multiple server instances. That's why this library provides two options for a fast key value store:



 - [Memcached](https://github.com/3rd-Eden/node-memcached) - store type `memcached`

 - [Redis](https://github.com/NodeRedis/node_redis) - store type `redis`



### blacklist.configure(options)



By passing `options` you can set the following:



 - `store.type` - Store type `memory`, `memcached` or `redis` (default: `memory`)

 - `store.host` - Store host (default: `127.0.0.1`)

 - `store.port` - Store port (default: `11211` memcached, `6379` redis)

 - `store.keyPrefix` - Key prefix for store to avoid collisions (default: `jwt-blacklist:`)

 - `store.options` - Additional store client options (default: `{}`)

 - `tokenId` - Unique JWT token identifier (default: `sub`)

 - `strict` - Strict revocation policy will return revoked `true` on store failure (default: `false`)



```javascript

blacklist.configure({

  tokenId: 'jti',

  strict: true,

  store: {

    type: 'memcached',

    host: '127.0.0.1'

    port: 11211,

    keyPrefix: 'mywebapp:',

    options: {

      timeout: 1000

    }

  }

});

```



### blacklist.isRevoked



This function it s plug-in for express-jwt [revoked tokens](https://github.com/auth0/express-jwt#revoked-tokens) function. It will take care of the `isRevoked` callback and handle the validation internally.



### blacklist.revoke(user)



This function will revoke a token, by passing in the `req.user` set by express-jwt library.



### blacklist.purge(user)



This function will purge **all** tokens older than current timestamp, by passing in the `req.user` set by express-jwt library.



### Custom store



You can implement your own store by passing `store` object that implements these two functions:



 - `get(key, callback)`

 - `set(key, data, lifetime, callback)`



### Considerations



User object `req.user` that's being set by the express-jwt library **should** contain and match `tokenId` from configuration.



- You need to set either `sub` or `jti` or some other key in the payload when siging a JWT token.

- Issued at `iat` timestamp should be present.

- Expiration timestamp `exp` is optional but desired.



## Why blacklist?



[JSON Web Tokens](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html) have many applications. One of the more popular one is using them as a **non-persistent** session tokens for your web app.



They are signed with a secret phrase or a private key, this makes token verification extremely fast, no database lookups just cryptography. Tokens are being issued once user has been successfully authenticated and contain expiration timestamp, they become invalid once the expiration time is up.



Tokens are usually stored on the client, browser cookie, local storage or some other store. By having a non-persistent session tokens we loose the ability to **revoke** them once they're out in the wild.



The Open Web Application Security Project states this in the [Session Management](https://www.owasp.org/index.php/Session_Management_Cheat_Sheet) section



 - **Session Expiration**: *"When a session expires, the web application must take active actions to invalidate the session on both sides, client and server. The latter is the most relevant and mandatory from a security perspective. In order to close and invalidate the session on the server side, it is mandatory for the web application to take active actions when the session expires, or the user actively logs out."*



 - **Privilege Level Change**: *"The session ID must be renewed or regenerated by the web application after any privilege level change within the associated user session. Previous session IDs have to be ignored, a new session ID must be assigned to every new request received for the critical resource, and the old or previous session ID must be destroyed."*



> Even without token revocation mechanism, using JWT tokens is considered secure as long as you **only** send them over secure connection SSL.



## Common use case



- User logs out of your web application, we want to invalidate this specific session token on the server so that it can't be used again. `blacklist.revoke(req.user)`



- User password change or permission change, we want invalidate all session tokens older than the time of this event. `blacklist.purge(req.user)`



## Testing



The unit tests are based on the [mocha](https://github.com/mochajs/mocha) module, which may be installed via npm. To run the tests make sure that the npm dependencies are installed by running `npm install` from the project directory.



    npm test

    

## Contributing



express-jwt-blacklist is an Open Source project maintained by Layer. Feedback and contributions are always welcome and the maintainers try to process patches as quickly as possible. Feel free to open up a Pull Request or Issue on Github.



## Author



[Nil Gradisnik](https://github.com/nilgradisnik)