@webgap/authorization-utils/README.md

WebGAP authorization module for express routes using Role-based Access Control - RBAC.

# WebGAP Authorization Utils

[![Build Status](https://travis-ci.org/webgap/authorization-utils.svg)](https://travis-ci.org/webgap/authorization-utils)
[![Test Coverage](https://codeclimate.com/github/webgap/authorization-utils/badges/coverage.svg)](https://codeclimate.com/github/webgap/authorization-utils/coverage)
[![Code Climate](https://codeclimate.com/github/webgap/authorization-utils/badges/gpa.svg)](https://codeclimate.com/github/webgap/authorization-utils)
[![Dependency Status](https://gemnasium.com/webgap/authorization-utils.png)](https://gemnasium.com/webgap/authorization-utils)

[![NPM version](http://img.shields.io/npm/v/@webgap/authorization-utils.svg?style=flat)](https://www.npmjs.com/package/@webgap/authorization-utils)
[![NPM downloads](http://img.shields.io/npm/dm/@webgap/authorization-utils.svg?style=flat)](https://www.npmjs.com/package/@webgap/authorization-utils)

# README

#### WebGAP Authorization module for Express.js

This is the Authorization utilities module for express routes using Role-based Access Control - RBAC.

# Dependencies

Handles notifications using [**@webgap/notifier**](https://github.com/webgap/notifier).

## Requirements

Requires [**passport**](https://github.com/jaredhanson/passport).<br/>
Requires [**express**](https://github.com/strongloop/express/).

## API

### Installation

```bash
npm install @webgap/authorization-utils --save
```

### Usage

It can be used as expressjs middleware:

```javascript
var Authorizator = require('@webgap/authorization-utils');
var authorizator = new Autorizator();
var Role = Authorizator.Role;
...
// set authorization required to all routes starting with
app.use('/admin', authorizator.isAuthorized([Role.ADMIN]));
app.use('/user', authorizator.isAuthorized([Role.USER]));
app.use('/provider', authorizator.isAuthorized([Role.PROVIDER]));
...
// or apply to individual troutes
  app.router.get('/account/settings', authorizator.isAuthorized([Role.USER]), function (req, res) {
    res.render('backend/account/settings.html');
  });
...
```

Or in the browser with a templating engine as a filter:

```javascript
<% if (authorizator.hasAccess(user, [authorizator.Role.ADMIN])) { %>
<span>Welcome Administrator!</span>
<% } %>
...
```

Check the tests for more info.

### Options


```javascript
var Authorizator = require('@webgap/authorization-utils');
var options = {
  notifier: { // default to @webgap/notifier module
    notify: function notify(options, callback) {
      console.log(options.notification); //render message as you want
      return callback();
    }
  },
  unauthorizedURL: '/unauthorized',
  loginURL: '/auth/login',
  unauthenticatedMessageKey: 'messages.warning.authentication-required',
  unauthorizedMessageKey: 'messages.error.authorization-required'
};
...
var authorizator = new Authorizator(options);
...
```

# License

Apache License, Version 2.0