Access Control Plus
Rich access control in an easy to read syntax featuring roles with inheritance, dynamic attribute tests, and more
npm install accesscontrol-plus
Features
- Write policies that are easy to read
- Define roles using inheritance
- Use async functions to test backend resources
- Restrict permissions to fields on the resource
- Get explanation why a permission was granted or denied
- Use wildcard matching for resources, actions and fields
- Define policies modularly
- Apply constraints to operations on the resource
- Use Typescript
Quick start
//// Create AccessControlPlus instance to manage a group of roles//; const accessControl = ; //// Define roles, scopes and conditions//accessControl action'*' create read // allow read on all fields but one update delete action'*'; { return userid == postauthorId;} //// Test whether permission is granted//let permission; permission = await accessControl;// permission.granted => truthy permission = await accessControl;// permission.granted => falsy permission = await accessControl;// permission.granted => truthy (because of inheritance) // using context:permission = await accessControl; // permission.granted => truthy
Concepts
Role Based Access Control (RBAC) versus Attribute Based Access Control (ABAC)
Role based authorization defines permissions in terms of roles in an organization - users, editors, authors, etc. This is convenient, but RBAC relies on static definitions and can't use contextual information (time, location, dynamic group membership, etc) to determine access rights. In traditional RBAC, contextual tests must be performed in other layers of an application. On the other hand, ABAC allows use of contextual information, but is also more complicated, and is sometimes described as overkill for solving typical problems. For more discussion, see: https://iamfortress.net/2017/02/15/ac-vs-abac/.
AccessControlPlus: RBAC with ABAC-powers
This library combines useful properties of RBAC and ABAC. You define roles and permissions, making it easy to define and manage your policies, like tradition RBAC, but also implement fine-grained context-sensitive tests, like ABAC.
The AccessControlPlus
class provides the top-level API of this library. Use it to define role permissions (using grant
or deny
), add conditions using where
, and
and or
, and test whether a permission (using can
). (See API).
;accessControl.deny'public'.scope'*:*';accessControl.grant'author'.scope'post:update' .whereauthorIsResourceOwner; // a function you write which tests attributes
Definitions
Roles, Resources, Actions and Inheritance
Each role
(e.g., "admin" or "user") has scopes
which grant or deny permission to perform actions
on resources
, potentially limited to certain fields
of the resource. Roles can inherit scopes from other roles.
Scopes
A scope
name is a resource:action
pair or a resource:action:field
triplet. For example,
"post:read" // read a post resource"post:read:text" // read the text field of a post resource
Shortcuts for creating scopes
const userRole = accessControl; // the following are all equivalent:userRolescope'post:create'userRoleaction'create'userRolecreate // see CRUD shortcuts
Effect: Grant or Deny
A scope has an effect, which is either grant
or deny
, which is determined by how the role is accessed.
E.g.,
const ac = ;ac scope'comments:read' // creates a grant scope scope'comments:*' // creates a deny scope
How permission is determined
Scopes are checked in the order defined.
Permission is granted if a grant
scope is found for the specified role
(or inherited roles) for the specified resource
, action
and optional field
. If no grant
scope is matched, the permission is denied where permission.denied
is an array of strings describing all the scopes which were attempted.
Permission is immediately denied if a deny
scope is matched.
Given, a request for a user role to read the text field of a post resource:
// request permission to read the text field of a post:const permission = accessControl;
- Look for the specified role (
user
)- if
user
doesn't exist, look for the*
role - if no role can be found, return a denied permission
- otherwise, continue
- if
- Look for the specified resource (
post
) on the role- if
post
resource doesn't exist, look for the*
resource - if no resource can be found, return a denied permission
- if
- Look for the
read
action- if
read
action doesn't exist, look for the*
action - if no action can be found, return a denied permission
- otherwise, there will be a list of one or more scopes defined for the action
- if
- Iterate through each scope
- Check whether the field (if requested in the call to
can
) is granted by the scope, and whether the condition (if provided) is satisfied. If these tests are satisfied, generate a permission and return it
- Check whether the field (if requested in the call to
- If no scope can be found for the current role, repeat this process for all inherited roles until finished
- If no permission was found, return a permission where
denied
contains descriptions of all the scopes which matched but failed
Permissions
A permission
is an instance of the Permission
class returned by AccessControlPlus#can
:
; // If the permission is granted, it is set to a "permission path", which// which shows which scope tested successfullypermission.granted === "grant:user:post:read:0:::" // if permission is denied, the permission paths of all scopes which were attempted//permission.denied === // the tests attempted and failed
If constraints were defined for the scope, the permission will contain a constraint
key.
permission paths
Permission paths are strings structured as:
"{grant|deny}:{role}:{resource}:{action}:{scopeIndex}:{field}:{conditionName}"
Note: the scopeIndex
indicates which
Conditions
Scopes can be restricted with conditions
, javascript sync or async functions of the form:
Conditions should be named functions. The condition name is used to generate a description string, assigned to permission.grant
// Add a condition to post:update:accessControlscope'post:update' ; // add a condition { return userid === resourceownerId;} permission = await accessControl; permissiongranted // => 'grant:user:post:update:0::userIsOwner'
If a condition throws an error, it is treated as though it returned false
. (Note: this may cause unexpected behavior if a condition is used to deny
, so this behavior may change in the future, such that exceptions will be treated as true
for deny
).
Context
The context
is a developer-specified value that is passed to the test function can
, which in turn passes the value to various developer-defined functions involved in testing scopes. Arbitrary values such as the current user, the request parameters, time, environment and location can be passed in the context. See the example above under Conditions.
;
Fields
Fields represent attributes of the resource. They can be allowed or denied using the onFields
method.
// E.g., Allow fields and disallow specific fields:accessControl.grant'user'.resource'post'.read.onFields'*', '!stats'; // request permission for action on a specific field:ac.can'user', 'post:read:stats'; // permission deniedac.can'user', 'post:read:foo'; // permission grantedpermission = ac.can'user', 'post:read';// permission granted with// permission.fields = { "*": true, "stats": false }
Alternatively, you can request a permission for the action, and you will receive a permission with a fields
property which is an object describing which fields are accessible:
ac.
Field permissions can also be calculated dynamically be providing a function (which can be async). The function returns an Object mapping field names to boolean values indicating whether the field is granted or not.
E.g., the following is equivalent to the `onFields` call shown above.
```typescript
accessControl.grant('user').resource('post').read.onDynamicFields((ctx: Context) => ({
'*': true, // grant all fields
stats: false
}));
API
AccessControlPlus
Top level object which exposes the API.
constructor
;const accessControl = ;
grant
Returns a Role object which can be used to grant permissions
// accessControl.grant(roleName)accessControl // => Role instance
deny
Returns a Role object which can be used to deny permissions
// accessControl.deny(roleName);accessControl // => Role instance
can
Async function returning a permission indicating whether the given role can access the scope:
// context is a developer-defined value passed to conditions// (see Scope #where, #and, #or)const context = user: id: 'the-user-id' ;// accessControl.can(role, scope, context)const permission = await accessControl;if permissiongranted // delete the user else // report access denied
The first argument can also be a list of role names.
Role
Represents a named role.
inherits
Inherit scopes from another role:
// role.inherits(roleName)role; // => Role instance
resource
Access a resource of a particular role:
// role.resource(resourceName)role; // => Resource instance
scope
Access a scope, a short cut for accessing a resource then accessing an action:
// role.scope(scopeName)rolescope'article:read'; // same as role.resource('article').action('read')
Resource
A resource object is obtained using the Role.resource
method
action
// resource.action(actionName)resourceaction'read'; // => Scope
Note: you can create multiple scopes per action. This allows you to provide different constraints and fields for the same action:
resource action'read' action'read' ;
CRUD shortcuts
resourcecreate // = resource.action('create');resourceread // = resource.action('read');resourceupdate // = resource.action('update');resourcedelete // = resource.action('delete');
Scope
Represents a specific permission, and enables setting conditions and constrains on the permission.
where
Sets one or more tests which must all pass for the permission to be granted. This method is equivalent to scope.and
, except for the name generated in the permission.grant
and permission.deny
:
// scope.where((context: Context) => boolean)// scope.where(async (context: Context) => Promise<boolean>) { const resource = await MyResource; return resourceid === userid;}scope; // => Scope
and
Grants permission for the scope if all of the tests return truthy values:
scope; // => Scope
or
Grants permission for the scope if any of the tests return a truthy value:
scope; // => Scope
withConstraint
Note: constraints are deprecated and may be removed from a future version of the API.
Add a function which returns a constraint useful to the developer for passing to a function that accesses a resource:
accessControlscope'article:create' ; // => Scope...let permission = await accessControl;if permissiongranted await Article; // { ownerId: 123 }
onFields
Restrict the grant/denial to specific fields. Provide a list of fieldNames. Use *
for all fields, !{fieldName}
to exclude a field:
// grant on all fieldsaccessControlscope'user:read' ;accessControl;// permission.granted => "grant:admin:user:read:0:superPrivateData:"
// deny on specific fieldsaccessControlscope'user:read' ;permission = await accessControl;// permission.granted => undefined// permission.denied = ["grant:admin:user:read:0:privateData:"]permission = await accessControl;// permission.granted = "grant:admin:user:read:0:name:"
// grant on specific fieldsaccessControlscope'user:read' ;await accessControl;// permission.granted => yesawait accessControl; // permission.granted => no
onDynamicFields
Generate field grants dynamically, given a context. You can use async calls, if needed:
accessControlscope'user:read' ;
Permission
Object returned by AccessControlPlus#can
granted
If permission granted this will be a string describing the scope granted.
denied
If permission denied, this is set to an array of objects that contain
field
Tests whether permission was granted for the specified field. Accounts for wildcards and denied fields (!foo
) provided in .onFields
.
permission // => true or false
Extended Example
; { return userid === resourceownerId;} { return userimpersonationId === resourceownerId;} { return resourcestate === 'published';} const ac = ;//// 4 roles in this scenario: public, author, admin, superadmin//ac // Define roles: // // PUBLIC // // start by disallowing the public access to everything scope'*:*' scope'article:read' // allow all fields except viewers // // AUTHOR // action'create' // add a constraint - to include when creating the article: action'read' // === .scope('article:read') action'update' // === .scope('article:update') // // ADMIN // action'read' // // SUPERADMIN // action'*'; //// The following are objects which are generated by your code// during a request - users, resources, etc://const user = id: 1234 ; // determined by request authenticationconst draft = ownerId: 1234 state: 'draft' text: '...' ; // retrieved from dbconst published = ownerId: 1234 state: 'published' text: '...' ; // retrieved from dbconst adminUser = id: 999 impersonationId: 1234 ;const superAdmin = id: 222 ; ; // permission.granted => truthy // public can't read draft articles permission = await accessControl.can('public', 'article:read', { user: null resource: draft }); // permission.granted => falsy // permission.denied = ['public:article:read:articleIsPublished'] // author can read their own draft article permission = accessControl; // permission.granted => truthy // auth can update their own article permission = accessControl; // permission.granted => truthy // admin cannot update an author's article, even if they are impersonating them permission = accessControl; // permission.granted => falsy // permision.denied = [ 'author:article:update:userIsResourceOwner' ] // admin can read a draft article if they are impersonating the author permission = accessControl; // permission.granted => truthy // superadmin can do anything to user resources permission = accessControl; // permission.granted => truthy}