express-jwt-policies

Lightweight JWT authentication & authorization middleware for Express.

• Usage
  • Authentication only
  • Authorization only
  • Asynchronous authorization
• Configuration
  • Module options
  • Authentication options
  • Authorization options

Developed at the Media Engineering Institute (HEIG-VD).

Usage

jwt-express-policies is an opinionated JWT-based authentication & authorization middleware. It assumes that:

• Authentication is performed by sending a JWT bearer token in the Authorization header.
• Some JWTs may optionally correspond to a resource (e.g. a user in the database) that you will need to load.

This module does not handle authentication or authorization errors for you. It simply passes them down the middleware chain, leaving you the responsibility of responding adequately to the user:

• Authentication errors will have the status property set to 401. Properties may also be added by express-jwt which is used to check the JWT.
• Authorization errors will have the status property set to 403.

const express = require('express');
const jwtExpressPolicies = require('jwt-express-policies');

// Configure the module.
const authorize = jwtExpressPolicies({

  // Provide a function to load the authenticated resource.
  authenticatedResourceLoader: function(req, res, next) {
    new User().where({ id: req.jwtToken.sub }).then(user => {
      req.currentUser = user;
      next();
    }).catch(next);
  },

  // Provide the secret used to sign JWTs.
  jwtSecret: 'changeme'
});

// Create policies.
const stuffPolicy = {

  // Any authenticated user can retrieve stuff.
  canRetrieve: function(req) {
    return req.currentUser;
  },

  // Only admins can create stuff.
  canCreate: function(req) {
    return req.currentUser && req.currentUser.hasRole('admin');
  }
};

// Create your routes and plug in authorization as middleware.
const router = express.Router();

router.get('/protected/stuff',
  authorize(stuffPolicy.canRetrieve),
  function(req, res, next) { /* retrieve implementation */ });

router.post('/protected/stuff',
  authorize(stuffPolicy.canCreate),
  function(req, res, next) { /* create implementation */ });

// Handle authentication/authorization errors.
router.use((err, req, res, next) => {
  res.status(err.status || 500).send(err.message);
});

Authentication only

// Configure the module.
const auth = jwtExpressPolicies({
  // ...
});

router.get('/protected/stuff',
  auth.authenticate(),
  function(req, res, next) { /* retrieve implementation */ });

Authorization only

// Configure the module.
const auth = jwtExpressPolicies({
  // ...
});

// Use the `authenticate` option of the `authorize` function to
router.get('/protected/stuff',
  auth.authorize(policy.canRetrieve, { authenticate: false }),
  function(req, res, next) { /* retrieve implementation */ });

Asynchronous authorization

Policy functions may return a promise to perform asynchronous checks:

const stuffPolicy = {
  canCreate: async function(req) {
    if (!req.currentUser) {
      return false;
    } else {
      const permissions = await fetchUserPermissions(req.currentUser);
      return permissions.indexOf('stuff:create') >= 0;
    }
  }
};

Configuration

Module options

These options can be passed to the function returned by require('jwt-express-policies') to configure the module:

• jwtSecret (string) required - The secret used to sign JWTs.

• jwtRequestProperty (string) - The property of the request to which the JWT should be attached (jwtToken by default).

  const auth = jwtExpressPolicies({
    jwtSecret: 'changeme',
    jwtRequestProperty: 'token',
    // ...
  });

• authenticatedResourceLoader (function) required - An Express middleware function that will be called when a valid JWT bearer token is sent in the Authorization header. The JWT will be available as the req.jwtToken property (by default). It should load whatever resource is identified by the token (e.g. a user) and attach it to the request (e.g. to the req.currentUser property) if necessary. You may do nothing but call next() in this function if the JWT is sufficient and nothing needs to be loaded.

  const auth = jwtExpressPolicies({
    authenticatedResourceLoader: function(req, res, next) {
      new User().where({ id: req.jwtToken.sub }).then(user => {
        req.currentUser = user;
        next();
      }).catch(next);
    },
    // ...
  });

• authenticationRequired (boolean) - If true, successful authentication is always required. Otherwise, an unauthenticated request will not cause an error. It is true by default. It can be set here at the module level, or overridden at every authentication or authorization call.

Authentication options

These options can be passed when calling the module's authenticate function:

• authenticationRequired (boolean) - Whether successful authentication is required. If true, an error will be passed through the middleware chain if no valid JWT is found in the Authorization header. If false, an unauthenticated request will not cause an error, and the authenticated resource loader will not be called. This defaults to the value of the authenticationRequired option provided when configuring the module (true by default).

The entire options object (including any custom option you might add) is attached to the request as req.authOptions.

Authorization options

These options can be passed when calling the authorize function (which is also the function returned by configuring the module):

• authenticate (boolean) - Whether to perform authentication before authorization. Defaults to true.
• authenticationRequired (boolean) - Whether successful authentication is required before performing authorization with the policy function. This defaults to the value of the authenticationRequired option provided when configuring the module (true by default).

The entire options object (including any custom option you might add) is attached to the request as req.authOptions.