SSOMG

This is the node client for the SSOMG single sign on project, designed to work with Express.

Setup

Add this package with the cli command

npm install --save ssomg

and require it in your root index.js file with

ssomg = require('ssomg');

and connect it to your express app like this

var app = express();
app.use(cookieParser()); // req.cookies must be set for sessions to work
ssomg.mount( app );

and then using the route protection middleware, limit route access to specific user roles.

var { protect } = require("ssomg")

router.use( protect("Read") );

or

var { protect } = require("ssomg")

router.get("/example", protect("Admin"), routeHandler )
router.get("/example2", protect(["Admin", "Read", "App Role 2"]), routeHandler )

Protect can either take a string or an array, depending on the number of roles you wish to authorise the route for.

Environment

When you register the app and the users in the main SSOMG admin, you'll be issued with an app id the public key used to verify tokens. You'll need to add the following attributes to your environment file to make sure it works correctly:

PUB_KEY_PATH=./keys/sso
APP_ID=xxxxxxxxxxxxxxxxxxxxxxxx
SSO_HOST=https://auth.mysite.com
NODE_ENV=production (this ensures secure cookies are used)

Using a .env file and with the npm package dotenv or docker is recommended. Set this up quickly by running npm install --save dotenv in the terminal, and require('dotenv').config() at the top of your app entrypoint.

Gotchas

Make sure the mount is after cookies are enabled Make sure the URLs in the env file and the provider app contain the correct protocol(http(s)), and ports. Without the correct protocols, the app will behave unexpectedly.

Details and customisation

Protect can accept an optional set of arguments to define what happens if the user is logged in but does not have permission: { failure_redirect: "The url to redirect to if failure occurs", failure_flash: "A flash message to set if failure occurs. Must have a req.flash() function present", failure_callback: function( req, res, next ) { /** This is a middleware function that is called when the user fails to authorize for a route. Supercedes failure_redirect and failure_flash */ } }

If a user JWT is set, req.user will be set like this:

"req.user": {
  "_id": "xxxxx",
  "first_name": "First",
  "last_name": "Last",
  "email": "[email protected]",
  "roles": [
    "App Role 1",
    "App Role 2"
  ],
  "refresh_token": "xxxxxxxxx",
  "iat": xxxxxxxxxx,
  "exp": xxxxxxxxxx
}

Who do I talk to?

If there's a problem, open an issue or talk to Henry.