Neglected Pulse Machine

    condor-authorize

    0.0.1 • Public • Published

    condor-authorize

    An authorization Middleware for Condor. Condor is a GRPC Framework for node.

    Build Status Coverage Status

    This module control access to GRPC methods, based on the access rules defined.

    Installation

    npm i --save condor-framework condor-authorize

    How to use

    Role-based authorization

    Just two steps:

    • Create a method that returns the roles / permissions the caller has.
    • Define the access rules
    const Condor = require('condor-framework');
    const jwt = require('condor-jwt');
    const authorize = require('condor-authorize');
    const Greeter = require('./greeter');
     
    const jwtOptions = {
      'secretOrPublicKey': 'shhhhhh', 
      'passthrough': true,
    };
     
    const authorizeOptions = {
      'getPermissions': (context) => {
        // do your magic here to obtain the permissions/roles from 
        // the token (or from anywhere else).
        // You just need to return an array of strings.
        return ['user', 'admin', 'another-string:my-permission'];
      },
    };
     
    const app = new Condor()
      .addService('./protos/greeter.proto', 'myapp.Greeter', new Greeter())
      .use(jwt(jwtOptions))
      .use(authorize(authorizeOptions))
      .start();

    As you can see, the example above uses condor-jwt to decode and verify a JWT token. The token will be then accessible in context.token.

    Any other strategy

    If you need more advanced authorization rules, you can skip the getPermissions method, and just use custom validators when defining the access rules.

    const Condor = require('condor-framework');
    const authorize = require('condor-authorize');
    const Greeter = require('./greeter');
     
    const app = new Condor()
      .addService('./protos/greeter.proto', 'myapp.Greeter', new Greeter())
      .use(authorize())
      .start();

    2. Access Rules

    By default, it will try to read the access rules from access-rules.js.

    The rules file should export an object, with the full names of the services as keys. Also you can have a default key.

    Rules Example

    This example will show you the available options:

    module.exports = {
      'default': '$authenticated',
      'myapp.Greeter': {
       'sayHello': 'special',
       'sayHelloOther': 'another:special',
       'sayHelloCustom': customValidation,
       'sayHelloPublic': '$anonymous',
       'sayHelloMultiple': ['special', 'realm:admin', customValidation],
      },
    };
     
    function customValidation (ctx) => {
        if (ctx.token.payload.someKey === 'someValue' && ctx.metadata.get('anotherKey')[0] === 'anotherValue') {
            return true; // allow to continue
        }
        return false; // deny access
    }

    Using these rules, we're telling the application:

    • By default, for every method not defined in the file, the user must be authenticated (without taking into account any roles).

    • sayHello requires the user to have the special permission/role.

    • sayHelloOther requires the user to have the another:special permission/role.

    • sayHelloCustom access will be calculated by the customValidation method.

    • sayHelloPublic will be public ($anonymous)

    • sayHelloMultiple shows how you can pass not only one but an array of options to authorize the call. In this example, to authorize the method we are requiring any of these 3 conditions:

      • The user to have the special permission/role.
      • The user to have the real:admin permission/role.
      • The customValidation method to return true.

    Rules Available

    $anonynous and $authenticated

    You can use $authenticated to enforce a user to be authenticated before accessing the method (without verifying any roles). By default a user is considered authenticated when the token received in the metadata is valid.

    On the other hand, you can use $anonymous to make a resource public. If you are using condor-jwt make sure to use the passthrough option (Otherwise it will never reach to this middleware, and authorization won't be performed.)

    String with the role/permission

    It will be matched against the array returned by the getPermissions method.

    Custom Validators

    If you need some specific logic to authorize/deny access, just pass the function that must perform the validation (make sure to pass the actual function, not only the function name).

    The validation function will be called with two parameters:

    • context: The context being processed.

    The validation function must return a truthy value to allow access. Any falsy value will deny access.

    Multiple options for a method

    You can pass not only one option, but an array of options to authorize the call. If any of them pass, the call will be authorized.

    How to require two roles/permissions? (use AND instead of OR)

    You can use custom validation functions that do exactly what you want. You can have for example something like this:

    module.exports = {
      'default': '$authenticated',
      'myapp.Greeter': {
       'sayHelloCustom': tokenHasAllRoles('special', 'admin'),
      },
    };
     
    function tokenHasAllRoles() {
     const roles = arguments;
     return (context) => {
       // Verify that the token has all the roles
       return roles.every((role) => {
         return context.token.payload.roles.contains(role);
       });
     };
    }

    Options

    All values are optional. Their default values are:

    Option Description
    rulesFile The path to the rules file. Default is access-rules.js
    rules The access rules to use (can be used instead of rulesFile)
    getPermissions Method to determine the permissions from the context. It receives the context, and must return (or resolve with) an array of strings.
    isAuthenticated Method to determine if a user is authenticated. It receives the context, and must return (or resolve with) true/false. By default it will consider a call authenticated if context.token is set, false otherwise.

    License and Credits

    MIT License. Copyright 2017

    Built by the GRPC experts at Devsu.

    Install

    npm i condor-authorize

    DownloadsWeekly Downloads

    0

    Version

    0.0.1

    License

    MIT

    Last publish

    Collaborators

    • c3s4r
    • devsu