npm: npmjs.com/package/@digipolis/authz

@digipolis/Authz

Authorization module which can be used to check the permissions of an authenticated user.

Table of contents:

• Installing
  • npm
  • Yarn
• Configuration
  • Example headers
  • Example With auth package / session
• Installation
• Usage
  • Usage as express middleware
  • Usage as function
  • permissions list
  • External authorization source
  • Permissionerror
    • Model
      • Error messages
      • Error detail
      • Error handling
• Running the tests
• Versioning
• Authors
• License

Installing

npm:

$ npm i @digipolis/authz

Yarn:

$ yarn add @digipolis/authz

Configuration

Available sources:

authzv2:

For applications which use the User Management Engine and have a JWT token of the authenticated user (mostly API's). Authzv2 works with jwt tokens. You can use the jwt-up policy to construct a jwt token for the upstream service.

meauthzv2:

For applications which use the User Management Engine and have an OAuth2 access token of the authenticated user (mostly BFF's). (This will not work for service accounts. The api-key will determine the consumer if there's no user detected. In this case the permissions will be checked for the consumer who has the contract instead of the consumer who requested the authorization header)

Configuration for the use with the User Management Engine (UM):

Params:

Param	Description	Values
debug (optional)	Set debugging mode	true / false (default)
disabled (optional)	Disable the authz check. This will allow everything for each token. Only for testing / dev purposes.	true / false (default)
source	The source to use by default. You can also specify a source in the function call	authzv2 / meauthzv2
sources	Object with possible authz sources and their configurations	{ authzv2: { _config_ }}
tokenLocation (optional)	Location of the token on the request object. Used by middleware. Defaults to 'headers.authorization'	headers.authorization / session.token (example)
cache (optional)	Enable cache. The permissions will be cached based for a token+source with a TTL of 600 (10min)	true (default) / false
authzv2: applicationId	Name of application from UM	_APPLICATION_ID_
authzv2: url	Url of the authz api (v2) You can find this on the api-store	_URL_OAUTHZ_
authzv2: apiKey	Api key. You will need to create an application with a contract with the authz api	_APIKEY_

Example with headers:

const { config } = require('@digipolis/authz');

config({
  debug: true,
  source: 'authzv2',
  tokenLocation: 'headers.authorization',
  sources: {
    authzv2: {
      url:  '_URL_AUTHZ_',
      apiKey: '_APIKEY_',
      applicationId: '_APPLICATION_ID_',
    },
    meauthzv2: {
      url:  '_URL_AUTHZ_',
      apiKey: '_APIKEY_',
      applicationId: '_APPLICATION_ID_',
    },
  },
});

Example with session or auth package:

This is a typical setup for bffs that need permission checks and are already using the Digipolis auth package or keeping accesstokens in express-session

const { config } = require('@digipolis/authz');

config({
  debug: true,
  source: 'meauthzv2',
  tokenLocation: 'session.userToken.accessToken', // The auth package saves the token at this location
  sources: {
    meauthzv2: {
      url:  '_URL_AUTHZ_',
      apiKey: '_APIKEY_',
      applicationId: '_APPLICATION_ID_',
    },
  },
});

Usage

The module can be used as an express middleware or as a function. The parameter is a string to check a single permission or an array to check multiple permissions. If a permission is missing an Error of the type PermissionError will be thrown.

An example of this can be found in the documentation below and in the example folder.

Usage as express middleware:

Configuration should be done before usage.

const { Router } = require('express');
const { hasPermission, hasOneOfPermissions } = require('@digipolis/authz');

const router = new Router();

// Check single permission in default source
router.get('/', hasPermission('login-app'), controller);
// Check multiple permissions in default source
router.get('/', hasPermission(['login-app', 'admin-app']), controller);
// Check permission in meauthzv2 source
router.get('/', hasPermission('login-app', 'meauthzv2'), controller);
// Check for one of permissions in meauthzv2 source
router.get('/', hasOneOfPermissions(['login-app', 'admin'], 'meauthzv2'), controller);

Usage as function:

Configuration should be done before usage.

const { checkPermission, hasOneOfPermissions } = require('@digipolis/authz');
const { create } = require('./itemcreator.service');

async function createSomething(params, usertoken) {
    await checkPermission(usertoken, 'login-app'); //throws error if invalid
    await checkPermission(usertoken, ['login-app', 'use-app']); //throws error if invalid
    await checkPermission(usertoken, 'login-app', 'meauthzv2'); //throws error if invalid
    await checkOneOfPermissions(usertoken, ['login-app', 'use-app'], 'meauthzv2'); //throws error if invalid
    return create(params);
}

External authorization source:

You can plug in your own implementation for retrieving permissions:

Requirements:

• Your function should take 1 argument: token. The token will be stripped from the Bearer prefixes.
• Permissions should be returned as an array.

const { checkPermission, config } = require('@digipolis/authz');
const controller = require('./controller');

function AuthzImplementation (token) {
    // Retrieve the users permissions here
    return ['permission1', 'permission2'];
}

config({
  debug: true,
  source: 'externalAuthz',
  tokenLocation: 'headers.authorization',
  sources: {
    externalAuthz: AuthzImplementation,
    meauthzv2: {
      url:  '_URL_AUTHZ_',
      apiKey: '_APIKEY_',
      applicationId: '_APPLICATION_ID_',
    },
  },
});

router.get('/', hasPermission('permission1'), controller); // Use own implementation (set as default)
router.get('/', hasPermission('login-app', 'meauthz'), controller); // Use defined meauthz implementation

Permissions list:

Retrieve permissions as a list

  // Default source (set in config)
  const permissions = await getPermissions(req.headers.authorization);

  // specific source
  const permissionsMeauthz = await getPermissions(req.headers.authorization, 'meauthz');

Returns: Array['string']:

[
    "PERMISSION_1",
    "PERMISSION_2",
    "PERMISSION_3",
]

PermissionError:

Model

{
  ...extends_default_javascript_error
  name: 'PermissionError',
  message: 'Failed to retrieve permissions.' // example
  detail: {
    message: 'Invalid Token' // example
  }
}

Error messages:

• ApplicationId not configured.
• Authzv2 not configured.
• meAuthz not configured.
• Missing permissions: permission1 Detail
• Failed to retrieve permissions. Detail
• No authorization found in header.
• No source defined for permissions
• No valid datasource defined for permissions
• Permission service returned permissions in an unexpected format

Error detail:

Failed to retrieve permissions (example):

{
  message: "Failed to retrieve permissions",
  detail: {"messsage": _error_message_authzv2_api_ }
}

Missing permissions (example):

{
  message: "Missing permissions: permission1",
  detail: {
    missingPermissions: ["permission1"],
    requiredPermissions: "permission1",
    foundPermissions: ["permission2"]
  }
}

Error handling:

Handle error from middleware:

function errorhandler(err, req, res, next) {
  if (err.name === 'PermissionError') {
    return res.status(401).json({
      message: err.message,
      detail: err.detail,
    });
  }
  return next(err);
}

module.exports = errorhandler;

Catch error from function:

try {
  await checkPermission(_TOKEN_, 'login-app');
  return do_something();
} catch (err) {
  if (err.name === 'PermissionError') {
    console.log('Detected authorization error');
  }
  // Handle error in express middleware
  return next(err);
}

Running the tests

Run the tests in this repo:

$ npm run test
$ npm run coverage

Dependencies

• axios: npm, Github
• node-cache: npm, Github

Versioning

We use SemVer

for versioning. For the released version check changelog / tags

Contributing

Pull requests are always welcome, however keep the following things in mind:

• New features (both breaking and non-breaking) should always be discussed with the repo's owner. If possible, please open an issue first to discuss what you would like to change.
• Fork this repo and issue your fix or new feature via a pull request.
• Please make sure to update tests as appropriate. Also check possible linting errors and update the CHANGELOG if applicable.

Support

Olivier Van den Mooter (olivier.vandenmooter@digipolis.be) - Initial work - Vademo

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details