This package has been deprecated

Author message:

Package no longer supported. Contact [e-mail] for more info.

express-jwt-blacklist-updated

express-jwt-blacklist

A library designed to be a complementary plugin for express-jwt middleware.

Simple example

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 - store type memcached
• 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)

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