Features

• Create CRUD routes for the passed models
• Add Bearer authentication to the individual routes
• Turn of the generation of specified routes

Usage

Prerequisites

This plugin requires you to have Bookshelf.js installed and configured. The reason for this is because it depends on the models to fetch table information and configure the routes correctly. In the future this requisite will be removed when there is time for it.

Installation

1. Require the library const api = require('roadwork')(serverObject, require('bookshelf')(require('knex')(config.database)))
2. Pass the Bookshelf models to the generate method to create the API calls, with: api.generate(User)

Database is a database connection object as described here: http://knexjs.org/#Installation-client

Authentication

Enable

To enable authentication, the only thing you need to do is call the Api.addAuthentication(authenticationLibrary) object. This will automatically create the user and user_session tables if they do not exist yet.

Once this is done, the addAuthentication will return a promise stating that it is done, whereafter you can generate the routings with their detailed permissions such as these routes:

// Create API routes
let api = new Roadwork(exports.server, require('bookshelf')(require('knex')(config.database)));
api.addAuthentication(require('roadwork-authentication'))
.then(() => {
    api.generate(require('./src/db/models/User'), {
        routes: {
            delete:  { allowedRoles: [ 'admin' ] },
            update:  { allowedRoles: [ 'admin' ] },
            findAll: { allowedRoles: [ 'admin', '$owner' ] },
            findAllWithPagination: { allowedRoles: [ 'admin', '$owner' ] },
            findOne: { allowedRoles: [ 'admin', '$owner' ] },
            count:   { allowedRoles: [ 'admin', '$owner' ] }
        }
    });
    api.generate(require('./src/db/models/UserSession'), {
        routes: {
            delete:  { allowedRoles: [ 'admin' ] },
            update:  { allowedRoles: [ 'admin' ] },
            findAll: { allowedRoles: [ 'admin', '$owner' ] },
            findAllWithPagination: { allowedRoles: [ 'admin', '$owner' ] },
            findOne: { allowedRoles: [ 'admin', '$owner' ] },
            count:   { allowedRoles: [ 'admin', '$owner' ] }
        }
    });

    return resolve();
})
.catch((err) => {
    console.error(err);
    return reject(err);
});

Configure route access

As soon as the authentication has been enabled, you will be able to fine tune access towards a single route. This can be done by specifying the allowedRoles in the configuration object (see API generate(model, options)).

This will also create a new dynamic role called $owner which will allow access to the requested resource only if the currently authenticated user owns it. This is usefull in cases such as updating the user's own model, ...

Example:

{
    "routes": {
        "update": {
            "allowedRoles": [ '$owner' ]
        }
    }
}

Generated Routes

• Supports filtering will show YES for the routes that accept column name filtering in their URL query, see the filters heading for more information

| route | description | Supports Filtering? | | ----- | ----------- | ------------------- | | GET /<model> | Gets all the objects for the specific model, if the $owner role has been added to rolesAllowed, then only the objects where the user has access to will be returned | YES | | GET /<model>/{id} | Gets the specified object for the given model, if the $owner role has been added to rolesAllowed, then only if the user has access this object will be returned | NO | | GET /<model>/pagination/{offset}?limit={limit} | Gets all the objects for the specific model starting at a specific id offset and a certain limit, if the $owner route has been added, only the objects where the user has access to will be returned. For an example response, see the responses below.| YES | | POST /<model> | Creates a specific item for the given model | NO | | PUT /<model>/{id} | Updates a specific item for the given model and id, if the $owner role has been specified, only the owner can update his/her own object | NO | | DELETE /<model>/{id} | Deletes a specific item for the given model and id, if the $owner role has been specified, only the owner can delete his/her own object | NO | | GET /<model>/count | Gets the number of items for the specific model, if the $owner object has been specified, only the amount of items where the owner has access to will be returned | YES |

Filters

TODO

Example Responses

Pagination

{
  "results": [
    {
      "id": 2,
      "id_social": "10205708189541043",
      "email": "[email protected]",
      "first_name": "Xavier",
      "middle_name": "",
      "last_name": "Geerinck",
      "scope": "admin",
      "avatar_url": "/images/avatar.png",
      "is_verified": 1,
      "email_date_sent": "0000-00-00 00:00:00",
      "created_at": "2016-02-13T15:10:33.000Z",
      "updated_at": "2016-02-13T15:10:33.000Z"
    },
    {
      "id": 3,
      "id_social": null,
      "email": "[email protected]",
      "first_name": "Satan",
      "middle_name": "Junior",
      "last_name": "Devil",
      "scope": "user",
      "avatar_url": "/images/avatar.png",
      "is_verified": 1,
      "email_date_sent": "0000-00-00 00:00:00",
      "created_at": "2016-02-13T15:10:33.000Z",
      "updated_at": "2016-02-13T15:10:33.000Z"
    }
  ],
  "pagination": {
    "offset": 1,
    "limit": 10,
    "rowCount": 3,
    "pageCount": 1
  }
}

API

generate(model, options)

generates the CRUD routes for the given model

{
    "routes": {
        "findOne": {
            "allowedRoles": [],
            "isEnabled": true
        },
        "findAll": {
            "allowedRoles": [],
            "isEnabled": true
        },
        "findAllWithPagination": {
            "allowedRoles": [],
            "isEnabled": true
        },
        "create": {
            "allowedRoles": [],
            "isEnabled": true
        },
        "delete": {
            "allowedRoles": [],
            "isEnabled": true
        },
        "update": {
            "allowedRoles": [],
            "isEnabled": true
        }
    }
}

addAuthentication(roadworkAuthentication, databaseConfiguration)

Adds the bearer authentication to the server authentication. This requires the route to have a Bearer: <token> header that specifies if the user is allowed access to the route.

The system will then look into the user_session table and confirm the user object.

RBAC Definition

• Principal: The subject, or the person who the roles applies to (example: administrator, user, ...)
• Action: What is happening? create, put, delete, ...
• Resource: The object where it is happening on
• Context: Extra constraints, such as only allow during midnight

Schema convention: <principals> CAN <actions> <resources> WHEN <conditions>

Route scheme

Routes are generated on the plural name of the base model separated by _ on the capital letters.

Example: User becomes /user Example: BaseUnit becomes /base_units

Patterns used

• adapter: Allows us to create a top level interface on an already existing library, ...
  • Example: Create an adapter to be able to use different SQL Engines (postgres, mysql, ...) while keeping the method the same
• facade: Provides a simplified interface to a larger body of code (such as a class library)
  • Example: the classes CarEngine, CarModel, CarBody, ... that we combine in the Car Facade which has a method: `assembleCar``
• spies: Are used to confirm that a function is called, these are used in the tests.
  • Example: Did we call the ORM functions, the Route registration functionsm ...