Home

nodeboot-oauth2-starter

Add this library to any express project to secure your endpoints using a mysql database. The library will create

Endpoint protection example

expressSecured.obGet('/', 'entity:select', (req, res) => {...});

Technologies required to know and use

• expressjs
• knex
• jwt
• mysql

Installation

Install the library with npm install https://github.com/usil/nodeboot-oauth2-starter.git and then import the library.

const OauthBoot = require("nodeboot-oauth2-starter");

Quick Start

From this

const expressApp = express();


expressApp.get('/employee', (req, res) => {...});
expressApp.post('/employee', (req, res) => {...});
expressApp.put('/employee', (req, res) => {...});
expressApp.delete('/employee', (req, res) => {...});

To This

const OauthBoot = require('nodeboot-oauth2-starter');

const expressApp = express();
const knex = knex({ client: 'mysql2', ... });

const oauthBoot = new OauthBoot(expressApp, knex, jwtSecret, cryptoSecret, [
  "extra",
]);

const securedExpress = oauthBoot.expressSecured;

await oauthBoot.init();

securedExpress.obGet('/employee', 'applicationPart:canRead', (req, res) => {...});
securedExpress.obPost('/employee', 'applicationPart:canCreate', (req, res) => {...});
securedExpress.obPut('/employee', 'applicationPart:canUpdate', (req, res) => {...});
securedExpress.obDelete('/employee', 'applicationPart:canDelete', (req, res) => {...});

How does it works

The application is based on following entities and concepts of nodeboot-oauth2-starter.

Subjects

An user or a client, the user has a username and a password to generate a jwt token and the client an id and a secret to do the same. For more information about the token generation take a look at the /auth/token endpoint documentation. A subject access to the application will be determined by the role that it has.

A client has 2 modes of access tokes a long live that can be only generated by the admin the long live token will not expire, in this case the client does not need to use the /token end point. The other mode is the short live token that endures a default of 2 hours however the time can be changed using the setTokenExpirationTime('<number>h') function. A client can not create a short live token if a long live one exists, the admin needs to first to remove the long live token.

Application

In the case of an standalone use your application where you will protect the endpoints. Using the distributed mode multiple applications that you will protect using the /auth/validate endpoint, check the endpoints section for more information.

Application part

The entities or processes that an application has. Those entities could be, for example, the application own tables. All parts have 5 basic options *, select, create, update, delete, where * is a wild card. However you can create as many options as you want The part and his options will be used to secure an endpoint using the access control string.

Access control string

An string that validates that a subject has the permission to access determinate endpoint. Has the following form applicationPart:option. You will need to pass this string like a middleware after using the library wrapper. The access control string is no other thing than a simple middleware, that will guard your endpoint to do this you will to send a jwt token on the header or an url query.

app.obGet('/api/someEndPoint', 'applicationPart:option', (req, res) => {...});

There it is an special value ':' that will disable the protection in the endpoint.

app.obDelete('/api/otherEndPoint', ':', (req, res) => {...});

Roles

The roles of an application, they join the application part with an option and then give them to a subject so the middleware added by this library can confirm a subject access to determined end point or validate his access by an endpoint.

Database

The library will ask for a knex connection to mysql, given that will create 7 main tables to manage your application security.

Tables

Table	Description
OAUTH2_Subjects	A user or client of the application, a subject can access or use different entities or processes of the application.
OAUTH2_Users	An user of the application will have an username and a password.
OAUTH2_Clients	A client of the application that will access it with an access_token.
OAUTH2_Applications	A list of the applications that this database supports.
OAUTH2_ApplicationPart	n,mj
OAUTH2_Options	The access options that each OAUTH2_ApplicationPart has.
OAUTH2_Roles	The roles of that an subject can have they are related to a list of application parts with its respective options.

OAUTH2_ApplicationPart, OAUTH2_Options and how to secure your endpoints

Lets suppose that you have an store application named superbuy and that you have the following processes, entities or parts:

• Sales
• Products
• Read accounting excel

For Sales you will create a sales column in the table OAUTH2_ApplicationPart, for Products a products one and finally for Read accounting excel read_accounting_excel. Each column will be create with at least those five options that will be put in the table OAUTH2_Options:

• *
• create
• update
• delete
• select

Then for example to protect sales you will need to use an access control string:

Method	Url	Access control string
POST	/sale	sales:create
GET	/sale	sales:select
PUT	/sale	sales:update
DELETE	/sale	sales:delete

In the case of the process you can either use any of the access control string like read_accounting_excel:create or create a new option like process and use it read_accounting_excel:process, it is up to you.

Contributors

Luis Huertas

JRichardsz