exacl
A rewrite of exacl with ES6 features and bugfix. .This module is an express/connect middleware module for enforcing an Apache Shiro inspired authorization system.
Installation
$ npm install exacl
Basic usage
const express = const app = const authorization = ; app
Documentation
Definitions
Permission - a statement that defines access to an explicit activity, behaviour or action.
Principal - usually a website user, assigned permissions to enable access to sets of activities, behaviours, or actions.
Permission Wildcard Expressions
To practically assign sets of permissions to principals, exacl supports a wildcard enabled permission statement syntax that closely follows the syntax used by Apache Shiro. A collection of permissions assigned to a principal are compiled by the system into a regular expression.
- Permission statements are composed of from parts delimited by colons
:
. - Wildcard
?
and*
can be used to match one or more characters within an expression part. - Examples:
Expression | Description |
---|---|
'system:*' |
String - has all permissions for system. Works for a single permission statement only |
[ 'system:*', 'activity:create', 'admin:users:roles:get:* ] |
Array - has all permissions for system and create permissions for activity and can retrieve all roles of all users |
Initialization
Create a new authorizer in for example a file name authorization.js:
var authorizer = ; moduleexports = authorizer;
Options
Setting options at initialization sets the default for that authorizer. The following options are available:
- withPrincipal - A Principal, usually a user, is expected to be represented by an object with a permissions property referring to either a single permission or an array of permissions. Defaults to req.user or req.session.user.
- onDenied - Callback function for when permission is denied. Defaults to setting the res.status to 403.
Setting the default principal
withPrincipal can be specified using an array, a function or an asynchronous function.
// Use any object that has a "permissions" parameter (array)var user = username : 'thisismyusername' permissions : 'account:view' 'payment:view' authorizeroptionswithPrincipal = user// OR use a function that returns a valid subjectauthorizeroptions { var user = username : 'thisismyusername' permissions : 'account:view' 'payment:view' return user}// OR use an asynchronous function that return a promise.authorizeroptionswithPrincipal = async { var user = await username : 'thisismyusername' permissions : 'account:view' 'payment:view' return user}
Setting the default onDenied callback
onDenied must be an express/connect compatible middleware function
authorizeroptions { resstatus403;}
Express Middleware
exacl uses a fluent API to generate express middleware for enforcing permissions.
const authorization = ; // Where the authorizer was configured previously. app