Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Action based authorization middleware.
tag: v0.2.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Action based authorization middleware

The authorized package is available on npm.

$ npm install authorized

Quick start

Import an authorization manager.

var auth = require('authorized');


Provide getters for your application roles.

auth.role('admin', function(req, done) {
  done(null, req.user && req.user.admin);

Roles can use <entity>.<relation> syntax.

// getters for entity.relation type roles are called with the entity
auth.role('organization.owner', function(org, req, done) {
  if (!req.user) {
  } else {
    done(null, !!~org.owners.indexOf(;


Provide getters for your application entities.

auth.entity('organization', function(req, done) {
  // assume url like /organizations/:orgId
  var match = req.url.match(/^\/organizations\/(\w+)/);
  if (!match) {
    done(new Error('Expected url like /organizations/:orgId'));
  // pretend we're going to the db for the organization
  process.nextTick(function() {
    // mock org
    var org = {id: match[1], owners: ['user.1']};
    done(null, org);


Now define what roles are required for your actions.

auth.action('add members to organization', ['admin', 'organization.owner']);

To perform the provided action, a user must have at least one of the given roles. In this case, a user must be admin or organization.owner to add members to an organization.

Note that entity and role getters can be added in any order, but you cannot configure actions until all entity and role getters have been added.


Now you're ready to generate authorization middleware.

var middleware = auth.can('add members to organization');

This middleware can be used in Connect/Express apps in your route definitions.

var assert = require('assert');
var express = require('express');
var app = express();
    auth.can('add members to organization'),
    function(req, res, next) {
      // you can safely let the user add members to the org here
      // you can also access entities, roles, and actions for your view
      var view = auth.view(req);
      assert.strictEqual(view.has('admin'), false);
      assert.strictEqual(view.has('organization.owner'), true);
      // this is implicit since this middleware is only called if true
      assert.strictEqual(view.can('add members to organization'), true);

Handling unauthorized actions

If the auth manager decides a user is not authorized to perform a specific action, an UnauthorizedError will be passed down the middleware chain. To provide specific handling for this error, configure your application with error handling middleware.

app.use(function(err, req, res, next) {
  if (err instanceof auth.UnauthorizedError) {
    res.send(401, 'Unauthorized');
  } else {

What else?

This package is strictly about authorization. For a full-featured authentication package, see PassportJS.

Inspiration is drawn here from connect-roles. One major difference is that this is all async (you don't have to determine if a user can perform an action synchronously).

Check out the tests for more

Tests are run with mocha.

npm test

Current Status

Something went wrong with that request. Please try again.