@c8/rbac

RBAC

A reusable package for permission based authorization with local or remote checks and express middleware.

Install

npm install --save @c8/rbac

Usage

Check the /examples folder.

API

const rbac = new Rbac(opts)

Creates a new Rbac instance with the given options for local or remote authorization. It also provides an express middleware that can use information in the request (i.e. the authentication token or principal) in the authorization process.

const rbac = new Rbac({
  remoteAuth: {
    url: 'http://www.example.com/authorize'
  }
})

app.get('/',
  rbac.express.authorizeRemote(['users:read']),
  (req, res, next) => {
    res.json({ message: 'You have acces to this awesome content!' })
  })

• opts {object} - Options object.
  • remoteAuth {object} (Optional) - Optional configuration object for allowing remote HTTP permission evaluation.
    • headers {object} (Optional) - Optional headers to pass in the HTTP request.
    • url {string} - Url for the HTTP request, required if opts.remoteAuth is set. The endpoint is expected to accept a JSON object with permissions {array} property and return 200 in case of success or different 200 in case of unauthorized. It can also return some claims about the principal (i.e. the user id) which will be merged with req.user, when called by the express middleware.
  • checkPermission {function} - Callback function for local permission evaluation with the signature function (id) and returning a Promise resolving to the principal permissions array. If opts.remoteAuth is not set, then this property is required.
  • getReqId {function} (Optional) - A callback with the signature (req) => {} that returns the principal ID from the HTTP request object. Defaults to (req) => req.user.id.

rbac.authorize(id, permissions)

Checks if a given principal is authorized for any of the given permissions. Returns a Promise resolving to the principal being allowed the permission. This function can authorize the principal locally, for which you need to define the checkPermission callback in the instance options.

• id {number} - The principal id to be checked against the permissions.
• permissions {array} - The permissions to be checked against the principal.

rbac.authorizeRemote(permissions, headers)

Checks if a given principal is authorized for any of the given permissions. Returns a Promise resolving to the principal being allowed the permission. The remote server can also return some claims about the principal, which will be returned in the Promise. This function can authorize the principal remotely, for which you need to define the remoteAuth object in the instance options.

• permissions {array} - The permissions to be checked against the principal.
• headers {object} (Optional) - Optional headers to pass in the HTTP request.

rbac.express.authorize(permissions)

Returns an express middleware function for checking if the principal who made the request is authorized for any of the given permissions. Parameters are the same as rbac.authorize, except for the id parameter which can be setup in the constructor options via the getReqId callback.

rbac.express.authorizeRemote(permissions)

Returns an express middleware function for checking if the principal who made the request is authorized for any of the given permissions. Parameters are the same as rbac.authorizeRemote, except for the headers parameter which can be setup in the constructor options via the remoteAuth.headers callback. It will define the authorization header as the current request authorization header.

Tests

The following commands are available:

• coverage for running code coverage with Istanbul (it shows the report at the bottom)
• standard for code style checks with Standardjs
• test for running Mocha tests

Versioning

This module adheres to semver versioning. That means that given a version number MAJOR.MINOR.PATCH, we increment the:

1. MAJOR version when we make incompatible API changes,
2. MINOR version when we add functionality in a backwards-compatible manner, and
3. PATCH version when we make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

License

The MIT License

Copyright (c) 2016 C8 MANAGEMENT LIMITED