Eg-cas-plugin NPM

express-gateway-plugin-cas

CAS plugin for Express Gateway with external Database

Installation

Simply type from your shell environment:

eg plugin install eg-cas-plugin

Quick start

Make sure the plugin is listed in system.config.yml file. This is done automatically for you if you used the command above. See Configuration for more details.
Add the configuration keys to gateway.config.yml file.

policies:
  - secure-auth:
  -
    basic-auth:
      -
        action:
          passThrough: true
  -
    jwt-auth:
      -
        action:
          passThroughSafeMethod: true

Configuration

The plugin requires a few configurations in system.config.yml.

plugins:
  cas:
    package: express-gateway-plugin-cas
    DATABASE_URL: 'postgres://username:password@localhost:5432/db_name'

Name	Description	Default	Require
DATABASE_URL	PostgreSQL Connection Url	-	Yes
AUTH_HEADER	a header for authenticated username	auth-user	-
ADMIN_KEY	custom api key, used for admin api authorisation	admin_key	-
JWT_SECRET	a string used to sign and verify jwt	jwt_secret	-
JWT_EXPIRATION_DELTA	This will be used to set the jwt expiration time.	null	-
JWT_REFRESH_EXPIRATION_DELTA	This is how much time after the original token that future tokens can be refreshed from.	null	-
USER_MODEL_PATH	path to sequelize model definition for a custom user model	null	-
ADMIN_CORS	the plugin is using Express Cors which follows Configuration Options	default

Note: JWT_EXPIRATION_DELTA, JWT_REFRESH_EXPIRATION_DELTA are strings describing a time span zeit/ms. Eg: "2 days", "10h", "7d". A string must provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120" is equal to "120ms").

The default configuration is the equivalent of:

{
  "origin": "*",
  "methods": "GET,HEAD,PUT,PATCH,POST,DELETE",
  "preflightContinue": false,
  "optionsSuccessStatus": 204
}

Policies

auth-secure:

Use to secure authenication of plugin
Recommended to be used as a first policy in a pipline

basic-auth:

The Basic Authorization policy follows the RFC-7617 standard. From the standard, if a user agent wanted to send the user-id “Aladdin” and password “open sesame”, it would use the following HTTP header.
Example: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

jwt-auth:

The policy can verify requests containing JSON Web Tokens. A token must be passed through the Authorization header with the scheme 'bearer'

Configuration Parameters

action.passThrough:

determines whether the gateway should execute the successive policy in case the auth process fails. If set to false, the gateway will return an Unauthorized response.
default value: false

action.passThroughSafeMethod:

same as action.passThrough, but determines only Safe Method
default value: false

Note: if you provide both actions, the action.passThrough has a higher priority.

Customization

User model

The plugin can import a custom model definition for User's table by providing a path to the exported model, otherwise it would use a default model.

We're using Sequelize ORM to connect to the SQL database, which support importing model definitions from a file. So, you can customize new model by using Sequelize model definition. And make sure that USER_MODEL_PATH has been set to your custom model in system.config.yml file.

The username and password field are required in custom model for authentication stuff. For security, there is a built-in password hashing feature. The password will be hashed automatically without extra configuration in your custom model.

For example, see custom-user-model.js.

Note: a path is relative to root project directory.

Example

drf-with-eg-cas is an example usecase of this plugin on top Express gateway and Django REST framework api

Running Test

Make sure you have the required environment variable as sample below

export DATABASE_URL=postgres://postgres:password@localhost:5432/postgres
export AUTH_HEADER=auth-user
export JWT_SECRET=this_is_a_secret
export ADMIN_KEY=this_is_an_admin_api_key

To able to run test first we will need a running server for requesting.

$ npm run start

Then open a new terminal (make sure you are in project directory), so that we can run our unit test with jest.

$ npm run test

Note that when you are developing you tend to change code often and every time you change code you must compile it. So to make thing easy, open another terminal window (make sure you are in project directory) and run