hapi-authorization

ACL support for hapijs apps

You can use this plugin to add ACL and protect your routes. you can configure required roles and allow access to certain endpoints only to specific users.

Support

Hapi >= 6

Usage

Note: To use hapi-authorization you must have an authentication strategy defined.

There are 2 ways to use hapi-authorization:

1. With the default roles which are: "SUPER_ADMIN", "ADMIN", "USER", "GUEST"
2. By defining your own roles

Using hapi-authorization with default roles

1. Include the plugin in your hapijs app. Example:

var plugins = [
    {
        plugin: require('hapi-auth-basic')
    },
    {
        plugin: require('hapi-authorization')
    }
];

server.pack.register(plugins, function(err) {
...

Using hapi-authorization with custom roles

1. Include the plugin in your hapijs app. Example:

var plugins = [
    {
        plugin: require('hapi-auth-basic')
    },
    {
        plugin: require('hapi-authorization'),
        options: {
            roles: ['OWNER', 'MANAGER', 'EMPLOYEE']	// Can also reference a function which returns an array of roles
        }
    }
];

server.pack.register(plugins, function(err) {
...

In order to activate the plugin for a specific route, add hapiAuthorization instructions with the role(s) that should have access to the route configuration.

Example:

Authorize a single role

server.route({ method: 'GET', path: '/', config: {
  auth: 'someAuthStrategy',
  plugins: {'hapiAuthorization': {role: 'ADMIN'}},	// Only ADMIN role
  handler: function (request, reply) { reply("Great!");}
}});

Authorize multiple roles

server.route({ method: 'GET', path: '/', config: {
  auth: 'someAuthStrategy',
  plugins: {'hapiAuthorization': {roles: ['USER', 'ADMIN']}},
  handler: function (request, reply) { reply("Great!");}
}});

Note: Every route that uses hapiAuthorization must be protected by an authentication schema on the route itself (auth: 'someAuthStrategy'). Currently can't just use auth.strategy.default()

Full Example using hapi-auth-basic and hapi-authorization

var Hapi = require('hapi');
var modules = require('./modules');

// Instantiate the server
var server = new Hapi.Server('0.0.0.0', 3000, {cors: true, debug: {request: ['error']}});

/**
 * The hapijs plugins that we want to use and their configs
 */
var plugins = [
    {
        plugin: require('hapi-auth-basic')
    },
    {
        plugin: require('hapi-authorization'),
        options: {
            roles: ['OWNER', 'MANAGER', 'EMPLOYEE']
        }
    }
];

var validate = function(username, password, callback) {
    // Perform authentication and callback with object that contains a role or an array of roles
    callback(null, true, {username: username, role: 'EMPLOYEE'});
}

/**
 * Setup the server with plugins
 */
server.pack.register(plugins, function(err) {

  // If there is an error on server startup
  if(err) {
    throw err;
  }

    server.auth.strategy('simple', 'basic', {validateFunc: validate});
    server.auth.default('simple');

    /**
     * Add all the modules within the modules folder
     */
    for(var route in modules) {
        server.route(modules[route]);
    }

    /**
     * Starts the server
     */
    server.start(function (err) {

        if(err) {
            console.log(err);
        }

        console.log('Hapi server started @', server.info.uri);
    });
});

Gotchas

Auth before routes

You must define your auth strategy before defining your routes, otherwise the route validation will fail.

Plugin Config

• roles - Array: All the possible roles. Defaults to SUPER_ADMIN, ADMIN, USER, GUEST
• hierarchy - Boolean: An option to turn on or off hierarchy. Defaults to false
• roleHierarchy - Array: The role hierarchy. Roles with a lower index in the array have access to all roles with a higher index in the array. With the default roles, this means that USER has access to all roles restricted to GUEST, ADMIN has access to all roles restricted to USER and GUEST, and SUPER_ADMIN has access to all roles restricted to ADMIN, USER, and GUEST.

Route config of supported parameters:

• role - String: enforces that only users that have this role can access the route
• roles - Array: enforces that only users that have these roles can access the route
• aclQuery - Function: fetches an entity using the provided query, it allows the plugin to verify that the authenticated user has permissions to access this entity. the function signature should be function(parameter, cb).
• aclQueryParam - String: The parameter key that will be used to fetch the entity. default: 'id'
• paramSource - String: The source of the acl parameter, allowed values: payload, params, query.
• validateEntityAcl - Boolean: Should the plugin validate if the user has access to the entity. if true, validateAclMethod is required.
• validateAclMethod - String: A function name. the plugin will invoke this method on the provided entity and will use it to verify that the user has permissions to access this entity. function signature is function(user, role, cb);