rest-bac
v1.0.0
Published
REST based access control list middleware for expressjs
Downloads
3
Readme
REST-bac
A REST based access control list middleware for Express applications.
This middleware allows to protect each method (GET,POST...) of any Express path (all the Express-style paths) with a set of custom roles specified in a configuration JSON.
Install
In your project root type
npm install rest-bac --save
Usage
To use the middleware you need an express application and a rest-bac configuration JSON. The express application should already provide a middleware or some other logic that set the req.user.roles property with an array of roles (string).
NB: the module protect exclusively the paths specified in the REST-BAC configuration JSON. If a business logic route path doesn't have a catching rest-bac path rule you have an Unhautorized 401 response.
JSON Configuration
The following configuration allow a "user" role to do GET requests to /book and all the paths under /book/* that don't match the path /book/admin/. An "admin" role can do POST and GET requests to /book and all its descendant paths /book/
{
"/book(/*)?": {
"get": ["user", "admin"],
"post": ["admin"]
},
"/book/admin/*": {
"action": "deny",
"get": ["user"]
},
"/author(/*)?": {
"get": ["user","admin"]
}
}
Initialization
To initialize the rest role based access control simply use
var restbac = require('rest-bac');
// some code to initialize the express app and the rest-bac configurations
// app is the expressjs application
// rbac-config is the JSON (parsed) object for the configuration
// prefix-path is an optional string to be prefixed to all the paths specified in the rbac-config
restbac(app, rbac-config, prefix-path)
Full Example
This is a full example to better understand how to use the middleware.
Server Application Code
This code can be found at /test/server.js. You can run and test it directly with node test/server.js
.
"use strict";
var express = require('express');
var restbac = require('rest-bac');
// some code to initialize the express app and the rest-bac configurations
var app = express();
// before use rest-bac the express app need to extract some roles from the request
// and put them in the req.user.roles array
app.use(function (req, res, next) {
req.user = {};
var auth = req.get('Authorization');
if (typeof auth != "undefined")
req.user.roles = auth.split(" ");
else
req.user.roles = [];
next();
});
var config = {
"/book(/*)?": {
get: ["user", "admin"],
post: ["admin"]
},
"/book/admin/*": {
action: "deny",
get: ["user"]
}
};
// setup the rest methods protection --> paths in config are prefixed with "/api/v1"
restbac(app, config, "/api/v1");
// now we can define some business logic API routes
app.get("/api/v1/book/:id", function (req, res, next) {
// user and admin roles can reach this function
res.send(req.params.id);
});
app.post("/api/v1/book", function (req, res, next) {
// only the admin can reach this function
res.send("POST OK");
});
app.get("/api/v1/book/admin/some", function (req, res, next) {
// only the admin can reach this function
res.send("admin path");
});
// a simple error handler to catch authorization error
app.use(function (err, req, res, next) {
// rest-bac authorization error propagate an Error object with a 401 status code
res.status(err.status || 500);
res.json({
message: err.message
});
});
var server = app.listen(3000, function () {
var host = server.address().address;
var port = server.address().port;
console.log('Example app listening at http://%s:%s', host, port);
});
Some requests
Valid request for a user role
GET /api/v1/book/123 HTTP/1.1
Host: 127.0.0.1:3000
Authorization: user
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 3
123
Invalid role cause a 401 with a json error message
GET /api/v1/book/123 HTTP/1.1
Host: 127.0.0.1:3000
Authorization: invalid
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 63
{"message":"Unhautorized: Invalid role or path not configured"}
The user cannot request a path under /api/v1/book/admin/*
GET /api/v1/book/admin/some HTTP/1.1
Host: 127.0.0.1:3000
Authorization: user
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 63
{"message":"Unhautorized: Invalid role or path not configured"}
GET /api/v1/book/admin/some HTTP/1.1
Host: 127.0.0.1:3000
Authorization: admin
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 10
admin path