node-utility-middlewaresdeprecated

A general purpose package of middlewares designed for Telus Digital Node projects

Usage no npm install needed!

<script type="module">
  import nodeUtilityMiddlewares from 'https://cdn.skypack.dev/node-utility-middlewares';
</script>

README

node-utility-middlewares

A package of general purpose middlewares for Telus Digital node projects

Purpose

The purpose of this package is to provide a few utility middlewares contextually specific to Telus Digital environments.

This includes:

  • Gate Middleware to easily control and prevent access

    • CorpGate controls access to traffic that is coming externally from outside of the Telus Enterprise Network (TEN) and is intended to be used by UI/BFFs
    • AuthProxyGate controls access to traffic that does not have the required tokens set by the AuthProxy (so traffic that is not from the AuthProxy)

  • Require Middleware to check and fulfill a request state before being resolve by the application

    • RequireSession checks to see if the SessionToken is set in the cookie, if not it fetches a new session token from AuthProxy, calls set-cookie on the response with the correct token and binds the token value to request.cookies.session
    • RequireOAuth2 checks to see if the oauth2 cookie is set, if not it calls set-cookie on the response with the correct token and binds the token value to request.cookies.oauth2

Usage

Requirements

This package assumes express is being used as the routing library. It has not been tested with koa, raw node http or other frameworks, and may rely on properties bound by express.

API Docs

requireSession.setEnvironment(environment:String [, host:String])

Tells the requireSession middleware which authProxy environment to use. The default state is production but staging and development are supported values.

By default, the common hosts for these authProxy environments are set but if host is passed in, it will use the passed value instead (which can be especially useful for development)

Common hosts:

  • production - https://api.digital.telus.com
  • staging - https://api.stage.digital.telus.com
  • development - http://local.telus.com:3000

requireSession.intercept(request:Object,responseObject,next:Function)

Intercepts incoming requests, checks the cookie for the correct token based on the previously set environment configuration, and if found translates it into the common request.cookies.session otherwise fetches a new token, sets the correct cookie header in response, and also binds it to request.cookies

Basic usage:

const requireSession = require('@telus-digital/node-utility-middleware').requireSession;

//By default will expect to use production authProxy
express.use(requireSession.intercept);

requireOAuth2.setEnvironment(environment:String [, host:String])

Tells the requireOAuth2 middleware which authProxy environment to use. The default state is production but staging and development are supported values.

By default, the common hosts for these authProxy environments are set but if host is passed in, it will use the passed value instead (which can be especially useful for development)

Common hosts:

  • production - https://api.digital.telus.com
  • staging - https://api.stage.digital.telus.com
  • development - http://local.telus.com:3000

requireOAuth2.setReturnHost(host:String)

Sets a base host that will be used to automatically generate the redirect if a user is required to login. This is optional, if a full redirect is being passed in to intercept.

requireOAuth2.redirectToLogin(response:Object, redirect:String)

Accepts a response object and a fully qualified redirect target, sets a 302 Location on the response to redirect to the AuthProxy target (based on config) with the redirect appended to return to the redirect target after successful login.

requireOAuth2.redirectToLogout(response:Object, redirect:String)

Accepts a response object and a fully qualified redirect target, sets a 302 Location on the response to redirect to the AuthProxy target (based on config) with the redirect appended to return to the redirect target after logout.

requireOAuth2.intercept(request:Object,responseObject,next:Function [, redirect:String])

Intercepts incoming requests, checks the cookie for the correct token based on the previously set environment configuration, and if found translates it into the common request.cookies.oauth2 otherwise fetches a new token, sets the correct cookie header in response, and also binds it to request.cookies.

Additionally has an optional redirect, which can be used to control the redirect for each request, otherwise if returnHost is set, the redirect is automatically generated as: returnHost+request.url

Basic usage:

const requireOAuth2 = require('@telus-digital/node-utility-middleware').requireOAuth2;

//Set the host domain to redirect back to
requireOAuth2.setReturnHost('https://myapp.host');

//By default will expect to use production authProxy
express.use(requireOAuth2.intercept);

corpGate.setEnvironment(environment:String)

If the environment is set to development, corpGate will allow all requests through.

corpGate.setDateThreshold(date:Date)

Accepts a Date object, and if set, checks the current time against the date object. If the current time is greater than the DateThreshold it will allow traffic through.

corpGate.setMode(mode:String)

Accepts whitelist or blacklist and controls the behavior for if route control is set.

corpGate.setRouteMap(routeMap:Object)

Accepts an object in the following format: routePattern:matchName

An example is as follows:

{
   '/version':true,
   '/*language/*province/test/page':true
}

If the mode was set to whitelist paths the following examples of paths would be let through:

  • /version
  • /en/bc/test/page
  • /fr/ab/test/page

Paths that did not succeed validation would not be allowed through. In reverse if the mode is set to blacklist everything would be let through except routes that matched the above patterns.

corpGate.intercept(request:Object,response:Object,next:Function)

This function is the interceptor for requests to control which are responded with a 404 or which are allowed to continue to the application.

Basic Usage

const corpGate = require('@telus-digital/node-utility-middlewares').corpGate;

//Deny all traffic that does not originate from within the Telus Enterprise Network
express.use(corpGate.intercept);

authProxyGate.setHostByEnvironment(environment:String)

Accepts production, staging, development and uses the standard AuthProxy hosts for these environments.

authProxyGate.setHost(host:String)

Sets the host target for authProxy manually.

authProxyGate.setWhiteList(routeMap:Object)

Accepts an object in the following format: routePattern:matchName

An example is as follows:

{
   '/version':true,
}

Used to allow certain paths through without verifying that the request came from AuthProxy (useful for healthCheck urls, etc)

authProxyGate.fetchPublicKey()

Returns a Promise that should resolve with the publicKey used by AuthProxy to verify and decrypt incoming JWT tokens.

authProxyGate.intercept(request:Object, response:Object, next:Function)

Intercept an incoming request, use (or fetch the publicKey if it hasn't already been fetched) to verify the request. If it cannot be verified, respond with 401, otherwise decrypt the available token headers and extract the ids from them and assign them to:

  • request.tokens.session
  • request.tokens.oauth2

Installation & Scripts

To install locally into your project run the following:

npm install @telus-digital/node-utility-middleware --save

If you wish to develop clone locally and run the following:

npm install
npm test

Maintainers

Current maintainers: Ian Reid (@anyuzer)