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

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

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();

expressApp.obGet('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obPost('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obPut('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obDelete('/', 'applicationPart:partOption', (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.

General usage

Starting the oauth library

You just need to declare the nodeboot-oauth2-starter class. To do this you will need to pass it the following values:

Value	Description	Requirement	Type
expressApp	Any express application	required	Express.app
knex	An knex connection using mysql	required	Knex
jwtSecret	A secret to encode your jwt tokens	required	string
cryptoSecret	A secret to encrypt the client secret	required	string
extraParts	An array containing extra basic application parts to add in the database creation	optional	string[]

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

The oauthBoot has the following variables:

Variable	Description	Type
expressApp	Any express application	Express
knex	An knex connection using mysql	Knex
expressSecured	A basic express application with extra functions to validate your endpoints	string
jwtSecret	A secret to encode your jwt tokens	string
cryptoSecret	A secret to encrypt the client secret	string
extraParts	An array containing extra basic application parts to add in the database creation	string[]
expiresIn	The jwt tokens expiration time	string

const securedExpress = oauthBoot.expressSecured;

Then you will need to call the init() function this will create, if not present or compatible, all of the required data base tables. This will also create a credentials.txt file with the user admin credentials and the client admin credentials. Then will add the protective middleware for your application and finally add a list of endpoints to create users, clients, applications, application parts, part options, roles and other endpoints to generate tokens and validate them.

await oauthBoot.init();

Using the securedExpress application

For now this nodeboot-oauth2-starter supports the GET, POST, PUT, DELETE methods. How to use:

Instead of:

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

Use:

expressApp.obGet('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obPost('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obPut('/', 'applicationPart:partOption', (req, res) => {...});
expressApp.obDelete('/', 'applicationPart:partOption', (req, res) => {...});

Accessing the protected endpoints

You will need a token, to generate jwt tokes you will need to call /auth/token?grant_type=<password or client_credentials> endpoint. Password for users and client_credentials for clients. The password and username of the user in the body, the client_secret and client_id in the query url if the subject is a client.

Given that token you can send it either in the query url with ?access_token=<token> or send it in the Authorization header with:

{
  "Authorization": "BEARER <token>"
}

Creating application parts, users, client and roles

You will have to create to create users, clients, application parts, options and roles. To do this you should use the manage endpoints present in the documentation.

If you are using angular you can also use our own angular library to have an graphic interface.

Standalone usage

For an stand alone usage in your back-end just follow the general usage part. You will not need to create other application just use the access control string to protect your endpoints.

Distributed usage

All of the general usage points stand however to protect an external api that is in lets say using .NET first create a new application lest say C# app that application will have an id that can be used to validate the access token. Each application has its own parts and options.

To validate an access token use the /auth/validate endpoint sending the application id and the part, the endpoint will give you the allowed options of the subject that the token belongs to.

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.

TODO

• Create typescript definition