express-gateway-plugin-cas

CAS plugin for Express Gateway with external Database

Installation

Simply type from your shell environment:

eg plugin install express-gateway-plugin-cas

Quick start

1. 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.

2. 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

---

Detailed documentation:

Express Gateway Overview

Express Gateway plugin explanation: Plugin Documentation

CLI for installing and configuring plugin: Plugins CLI

Guidlines how to write your custom plugin: Plugin Development Guide

Express Gateway Boot Sequence explains order in which plugin entities are loaded and executed.

Want to make your own plugin?

Just check out our plugin development guide. We can't wait to see your custom stuff in the Gateway!