express-authz v1.0.1

Authz

rules and policy based authorization middleware

The expreess-authz package is available on npm.

$ npm install authz

This middleware package is meant to ride alongside authentication (such as PassportJS) and provide route specific access authorization based on rules that you provide. The rules are arbitrary, and can be tied into whatever data model or access system you care to use.

Quick start

Import authorization

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

Set up rules for authorizations

authorization.addRule('allAccess', function() {
    return true;
});
authorization.addRule('noAccess', function(req) {
    return false;
});

The function you provide should return something truthy to allow access, or false otherwise. The function will be passed in the req object from express, and you can operate on anything annotated onto that object.

authorization.addRule('applicationOwner', function(req) { 
    // PROTIP: when comparing BSONid from Mongoose, do comparisons with
    // .equals(), not == or ===
    return (req.application.owner.equals(req.user._id));
});

authorization.addRule('gmailAccount', function(req) {
    // email address of user contains renasar.com
    return (req.user.email.search('gmail.com') > 0);
});

Set up policies that are sets of rules

Once you've added rules, you create policies, referencing the names of the rules you provided earlier. Note that a "falsey" return from an rule check will not immediately error and fail, only fall through to the next check.

authorization.addPolicy('applicationOwner', ['applicationOwner', 'renasarian']);
authorization.addPolicy('nobody', ['noAccess']);

Utilize the middleware

When enforcing, the middleware will process the rules in the order that you provide, short-circuiting to allow access if any of the rules returns true. If none of the rules returns true, then the middleware will return an annotated Error using next() down the middleware chain. It is expecting you to have an error handler somewhere in that chain that will return a response that you prefer based on the authorization failure.

var express = require('express'),
    router = express.Router(),
    authz = require('express-authz');

router.route('/some/path/:Id')
    .get(authz.enforcePolicy('applicationOwner'), function (req, res, next) {
        ... your route logic here ...
    });

The middleware can be used in Connect/Express apps in your route definitions, as generic middleware, etc.

handling unauthorized access

If the authorization fails, the middleware will pass down an Error annotated with a 'status' of 403 down the middleware chain. Configure or create an error handler to send a response based on this error:

app.use(function(err, req, res, next) {
  if (err.status) {
    res.send(err.status)
  } else {
    next(err)
  }
});

Authentication

This package is for adding authorization over the top of authentication. For a full featured authentication package, see PassportJS.

tests

npm test