README
Express authorization
Express-rbac is an Express-compatible roles and permissions authorization middleware for Node.js.
Express-rbac purpose is to provide traditional roles and permissions authorization to connect/ express applications, which it does through a middleware and a set of functions for runtime strategies. Using express-rbac is really simple. Only hook up the library to the express pipeline providing a callback function for loading the user roles and permissions. Once the library is hooked up on the pipeline, just use the 4 built in available handlers for route authorization, or the 4 functions added to the request object to be able to provide runtime strategies regarding the user's roles and permissions.
Install
> npm install express-rbac
Usage
Examples
Theres an easy to follow and fully functionl example using Passport.js authentication in the "\examples" folder:
You can view it <here>
Registration
Before using express-rbac, the library should be initialized and hooked up to the pipeline.
var express = require('express');
var app = express();
/*
* Require the library
*/
var auth = require('express-rbac');
/*
* Hook up the library to the express pipeline.
* Be sure this is done AFTER authentication.
* The callback function will receive the
* request object. So if your authentication library
* populates the request (like passport.js for example)
* you could use its data on the function itself.
* Once you load the user's roles and permissions, use them as a parameter for the done() callback.
*/
app.use(auth.initialize({
// Use this parameter for binding the library methods to a specified
// object, instead of the req object itself. For example on passport.js
// default implementation, the user information is stored in the 'user'
// property, as specified on this particular example.
bindToProperty: 'user'
}, function(req, done) {
// Get your users roles and/ orpermissions.
var auth = {
roles: ['Super Admin', 'User'],
permissions: ['CanAddContent', 'CanRemoveContent']
};
done(auth);
})
);
Route handlers Authorization
The following route handlers for path authorization are provided.
auth.isInRole(string | number | array)
This method validates against one or more specified roles. If multiple roles specified, all should evaluate to true.
app.get('/someauthorizedpath',
auth.isInRole('Super Admin'),
function (req, res) {
...
}
);
app.get('/someauthorizedpath',
auth.isInRole(['Super Admin', 'Content Editor']),
function (req, res) {
...
}
);
auth.isInAnyRole(string | number | array)
This method validates against one or more specified roles. If multiple roles specified, only one should evaluate to true.
app.get('/someauthorizedpath',
auth.isInAnyRole('Super Admin'),
function (req, res) {
...
}
);
app.get('/someauthorizedpath',
auth.isInAnyRole(['Super Admin', 'Content Editor']),
function (req, res) {
...
}
);
auth.hasPermission(string | number | array)
This method validates against one or more specified permissions. If multiple permissions specified, all should evaluate to true.
app.get('/someauthorizedpath',
auth.hasPermission('canEditContent'),
function (req, res) {
...
}
);
app.get('/someauthorizedpath',
auth.hasPermission(['canEditContent', 'canDeleteContent']),
function (req, res) {
...
}
);
auth.hasAnyPermission(string | number | array)
This method validates against one or more specified roles. If multiple roles specified, only one should evaluate to true.
app.get('/someauthorizedpath',
auth.hasAnyPermission('canEditContent'),
function (req, res) {
...
}
);
app.get('/someauthorizedpath',
auth.hasAnyPermission(['canEditContent', 'canRemoveContent']),
function (req, res) {
...
}
);
Runtime check and strategies
Express-rbac will register its four authorization check functions into the request object for providing runtime evaluation and authorization strategies.
Note: in case where the "bindToProperty" option is used, the functions will be registered to the request's specified object.
Note: this functions will only be available after hooking up the library to the pipeline.
/*
* Without bindToProperty
*/
app.get('/somepath',
function (req, res, next) {
...
/*
* All function are sync and return tue or false;
*/
var isAllowed = req.isInRole("Content Editor");
...
var isAllowed = req.isInAnyRole(["Content Editor", "Auditor"]);
...
var isAllowed = req.hasPermission(45);
...
var isAllowed = req.hasAnyPermission(["canAddUser", "canUpdateUser"]);
...
}
);
/*
* With bindToProperty: user
*/
app.get('/somepath',
function (req, res, next) {
...
/*
* All function are sync and return tue or false;
*/
var isAllowed = req.user.isInRole("Content Editor");
...
var isAllowed = req.user.isInAnyRole(["Content Editor", "Auditor"]);
...
var isAllowed = req.user.hasPermission(45);
...
var isAllowed = req.user.hasAnyPermission(["canAddUser", "canUpdateUser"]);
...
}
);
Tests
> npm install
> npm run test
Contributing
- Clone the repo
- Make the required changes
- Modify/ add tests where required
- Ensure all tests succeed. npm run test
- Create PR.
Credits
- Hernan Bazzino