franciscogouveia / rbac-core

The RBAC core from hapi-rbac

rbac-core

The RBAC core from hapi-rbac

This is inspired by the XACML policies.

Versions

• 1.0.0 Release Notes
• 2.0.0 Release Notes
• 3.0.0 Release Notes

How to use it

First, install

npm install --save rbac-core

Import it to your project

const Rbac = require('rbac-core');
const DataRetrievalRouter = Rbac.DataRetrievalRouter;

Create your data sources in the data retrieval router

const dataRetrieverRouter = new DataRetrievalRouter();

/**
 * register(prefixes, dataretriever): registers a data retriever.
 *
 * prefixes - a string or array of strings with prefixes which this data retriever will be associated
 * dataretriever - a function with the following signature
 *         source - The requested prefix
 *         key - the key being requested
 *         context - An object with contextual information
 **/
dataRetrieverRouter.register('credentials', (source, key, context) => {

    // Obtain your value (e.g. from the context)
    const value = context.user[key];

    return value;
});

// You can handle multiple prefixes with a single data retriever
dataRetrieverRouter.register(['connection', 'status'], (source, key, context) => {

    let value;

    switch (source) {
        case 'connection':
            // Obtain connection info
            value = context.connection[key];
            break;
        case 'status':
            // Obtain from somewhere else
            value = getStatusValue(key);
            break;
    }

    return value;
});

Evaluate your policies against a certain context

const context = {
    user: {
        username: 'francisco',
        group: ['articles:admin', 'articles:developer'],
        validated: true,
        exampleField1: "test-value"
    },
    connection: {
        remoteip: '192.168.0.123',
        remoteport: 90,
        localip: '192.168.0.2'
        localport: 80,
        exampleField2: "test-value"
    }
};

dataRetrieverRouter.setContext(context);

const policy = {
    target: [
        // if username matches 'francisco' OR (exampleField1 matches exampleField2 AND user group matches 'articles:*')
        { 'credentials:username': 'francisco' },
        // OR
        {
            'credentials:exampleField1': { field: 'connection:exampleField2' }
            // AND
            'credentials:group': /^articles\:.*$/ //(using native javascript RegExp)
        }
    ],
    apply: 'deny-overrides', // permit, unless one denies
    rules: [
        {
            target: { 'credentials:group': 'articles:admin', 'credentials:validated': false }, // if group is 'articles:admin' AND is not validated
            effect: 'deny'  // then deny (deny access to users that are not validated)
        },
        {
            target: { 'connection:remoteip': ['192.168.0.2', '192.168.0.3'] }, // if remoteip is one of '192.168.0.2' or '192.168.0.3'
            effect: 'deny'  // then deny (deny blacklisted ips)
        },
        {
            effect: 'permit' // else permit
        }
    ]
};

Rbac.evaluatePolicy(policy, dataRetrieverRouter, (err, result) => {

    switch (result) {
        case Rbac.PERMIT:
            console.log('ACCESS GRANTED');
            break;
        case Rbac.DENY:
            console.log('ACCESS DENIED');
            break;
    }
});

If you want to extend your existent data retriever router, you can do it.

// You can just extend
const dataRetrieverRouter1 = dataRetrieverRouter.createChild();

// You can also directly add context to the extension, for isolation
const dataRetrieverRouter2 = dataRetrieverRouter.createChild(context);

Both dataRetrieverRouter1 and dataRetrieverRouter2 will have all the registered data retrievers from dataRetrieverRouter.

Changes to dataRetrieverRouter will influence dataRetrieverRouter1 and dataRetrieverRouter2.

Changes to any of dataRetrieverRouter1 or dataRetrieverRouter2 will not cause influence on any data retriever routers, but themselves.

Contexts are preserved per data retriever router.

You can also get data from data retriever router

dataRetrieverRouter.get('credentials:username')
.then((result) => {...})
.catch((err) => {...});

And you can override the context on get, by passing it in the second argument

dataRetrieverRouter.get('credentials:username', { username: 'the_overrider', group: ['anonymous'] })
.then((result) => {...})
.catch((err) => {...});

Learn more about Rule Based Access Control

To have a better idea of how this works, you can check my Bachelor's project presentation about XACML here (english), or here (portuguese).

Even though this plugin doesn't implement the XACML specification, it was based on its policies.