MustBe: Authorization Plumbing For NodeJS / Express Apps
MustBe is not a complete authorization framework, with roles and responsibilities and models and data access and everything that you need. Rather, it is the underlying plumbing that you need to secure your site. It allows you to fill in the necessary parts to manage data access, roles and users, and gives you the activity based plumbing to secure it all.
Authorization, Not Authentication
MustBe is an authorization system - the part of a security system that decides whether or not you are allowed to do something. This is the second of authentication and authorization, where authentication simply determines who you are.
Specifically, MustBe is an activity based authorization system. It allows you to verify that a user has permissions to perform any given activity in your application.
What Is Activity Based Authorization?
The gist of it is that you check whether or not a user has permission to perform an activity. How they get permission to do that activity is up to you. Maybe it's throug a role, maybe it's through data they have been assigned to. But the permission for the activity is what needs to be checked.
For more detail on this, check out my 2011 article on using activity based authorization checks. It will give you the core of what you need to know about whey role-based authorization checks are a bad idea, and why activity based permissions are the way to go.
Documentation
Detailed documentation about the configuration and use of MustBe can be found in the documentation folder.
Demo App
There is a small demo app located in the /demo folder of this repository. You can run the demo app by first installing the dependencies for mustbe with:
npm install
And then going in to the demo folder and running the following:
npm install
npm start
Now go to http://localhost:3000
and you will see a small
demonstration of various MustBe features.
Getting Started
The first thing you need to do is install MustBe, and save it to your package.json file.
npm install --save mustbe
Configure Once In Your App
In your app.js (or whatever bootstraps your app), require the MustBe module, and also bring in a mustbe-config module which you will define in a moment.
Call the .config
method
on the mustBe
object, and pass in the function that is
exported from the config module.
// app.js
var mustBe = require("mustbe");
var mustBeConfig = require("./mustbe-config");
mustBe.configure(mustBeConfig);
Create The Configuration
Now you can create a mustbe-config.js
file for your application.
Having the config file separate from the app.js
bootstrapper
file helps to keep things clean.
Open the mustbe-config.js
file and build your configuration.
Provide configuration for your user identity, route helpers,
activities and/or overrides.
Here is a basic configuration example from which you can start:
// ./mustbe-config.js
var mustBe = require("mustbe");
module.exports = function(config){
config.routeHelpers(function(rh){
// get the current user from the request object
rh.getUser(function(req, cb){
// return cb(err); if there is an error
cb(null, req.user);
});
// what do we do when the user is not authorized?
rh.notAuthorized(function(req, res, next){
res.redirect("/login?msg=you are not authorized");
});
});
config.activities(function(activities){
// configure an activity with an authorization check
activities.can("view thing", function(identity, params, cb){
var id = params["id"];
someLib.anotherThing(id, function(err, thing){
if (err) { return cb(err); }
var hasThing = !!thing;
cb(null, hasThing);
});
});
});
};
Now you can run the mustBe
functions on your routes.
var mustbe = require("mustbe").routeHelpers();
var express = require("express");
var router = express.Router();
router.get("/:id", mustBe.authorized("view thing"), view);
function view(req, res, next){
res.render("/something");
}
Be sure to read the full documentation, linked above, for the complete set of options and methods that can be called to configure and use MustBe.
Legal Junk
MustBe is Copyright 2014 Muted Solutions, LLC. All Rights Reserved.
Distributed under MIT License.