Getting started with Gateman.JS for Node app authorization

Celý článek

Gatemanjs is an authorization system designed to manage roles and claims in node applications that use mongodb for data storage. It works together with mongoose to provide a fluent approach to managing roles and claims.

Why use Gateman?

• It enables easy role management with less code
• It uses MongoDB for role authoraization which is more secure than web tokens and sessions

Perquisite

This article presumes you have Node and Mongoose installed on your device

Installation

It is simply installled by running:

# using npm
npm install gatemanjs --save

# or using yarn
yarn add gatemanjs

Getting started

Since Gateman.js is a middleware using mongoose models as a depedency, we would have to import the Gateman package and setup the gateman class using a mongoose connection object like so:

var mongoose = require('mongoose');
var gateman = require("gatemanjs").GateMan(mongoose);

Working with Gateman.JS

I will be using a simple Admin , user example to explain how Gateman.js works.

Note:

Roles: These are different job functions avaliable to users in the database Claims: These are functional privilages or individual actions that can be assised to roles

Creating roles and claims

Gateman.js helps to reduce the amount of code used for authorization, by breaking it down authorization paths into Roles and claims with understandable syntax .We create roles using gateman as so gateman.createRole(roleName); Here is a code example showing how to create an admin role.

gateman.createRole("admin").then((role)=>{
        console.log(role);
    }).catch((err)=>{
        console.log(err);
    });

Also making claims are similar to creating roles: gateman.createClaim(claimName); Here is a code example showing how to create a claim let enables deleting.

gateman.createClaim("delete").then((claim)=>{
        console.log(claim);
    }).catch((err)=>{
        console.log(err);
    });

Linking roles to claims

When the admin wants to claim deleting previlages we link this as so gateman.allow('role').to('claim');

gateman.createRole("admin").then(role=>{
    gateman.allow("admin").to("delete").then(result=>{
        //result is true if claim was assigned successfully
    }).catch(err=>{
        //err contains the error message, if any
    });
})

Removing a claim from a role.

In the use case where an Admin account has to be reverted to a user, we can remove the claim by

gateman.disallow('role').from('claim').then(result=>{
    //result is true if claim was retracted
}).catch(err=>{
    //err contains any error message, if any
});

Note: If the claim isn't assigned to the specified role it does nothing.

And in case you forgot to assign a claim to a role, Gateman.js helps you check by

gateman.role('rolename').can('claimname').then(result=>{
    //result is true if the claim has been assigned, else it will be false
});

//Checking for errors

gateman.role('rolename').can('claimname').then(result=>{
    //you can user result here
}).catch(err=>{
    //err contains error message if any
});

Using Gateman.js with user models

Setting up your User model to extend the HasRolesAndClaims class from the gateman package, this allows the user to perform a claim

const mogoose = require('mongoose');
const hasRolesAndClaims = require('gatemanjs').hasRolesAndClaims(mogoose);

var UserSchema =  mongoose.Schema({
    name: String,
    email: String
});

UserSchema.loadClass(hasRolesAndClaims);
module.exports = mongoose.model('User',UserSchema)

Allowing users to perform a claim

UserModel.findOne({name: "Obinna"}, (err, user)=>{
    user.allow("claim")
        .then((userClaim)=>{
            console.log(userClaim);
        }).catch((err)=>{
            console.log(err);
        });
    });

//Disallowing a user from performing a claim

UserModel.findOne({name: "Obinna"}, (err, user)=>{
    user.disallow("claim")
        .then((message)=>{
            console.log(message);
        }).catch((err)=>{
            console.log(err);
        });
    });

Note: The Gateman hasRolesAndClaims class is loaded into a valid mongoose model which means that the methods are only accessible to valid user objects.

Validate if user exsits

UserModel.findOne({name: "Obinna"}, (err, user)=>{
    user.assign("role")
        .then((userRole)=>{
            console.log(userRole);
        }).catch((err)=>{
            console.log(err);
        });
    });

To validate that a claim has been correctly assigned to the right user use we can check like so:

User.findOne({name: "Obinna"}, (err, user)=>{
        user.isA("role").then((userHasRole)=>{
            if (userHasRole){
                //user belongs to role
            }
        });
    });

//To verify if a User can perform an claim

User.findOne({name: "Obinna"}, (err, user)=>{
        user.can("claim").then((hasClaim)=>{
            if (userHasClaim){
                //user can perform claim
            }
        });
    });

Retracting a role form a user

UserModel.findOne({name: "Obinna"}, (err, user)=>{
    user.retract("role")
        .then((message)=>{
            console.log(message);
        }).catch((err)=>{
            console.log(err);
        });
    });

Getting list of claims

we can get a list of the existing roles by

gateman.getRoles().then(roles=>{
    //roles is a collection of existing roles
}).catch(err=>{
    //err contains the error message, if any
});

.getRoles() is a callback function that shows the list of rolls

Conclusion

Gateman.js is a hack for Authorization, with less code and it is open source. I will really recommend checking it out and contributing to the project. Happy Coding!