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.
You can install gateman using npm package manager.
npm install gatemanjs
Before using gateman in your node application, you'll have to import the gateman package and setup the gateman class by passing in a valid mongoose connection object
var mongoose = require('mongoose');
var gateman = require("gatemanjs").GateMan(mongoose);
You have to create a role before using it in your application, Gateman provides an easy way of doing that.
//Syntax
gateman.createRole(roleName);
//Example
let role = await gateman.createRole("rolename");
Creating claims is similar to creating roles
//Syntax
gateman.createClaim(claimName);
//Example
let role = await gateman.createRole("claimname");
//Syntax
gateman.getRoles(callback);
//Example
let roles = await gateman.getRoles();
Adding claims to roles is made extremely easy. You do not have to create a claim in advance. Simply pass the name of the claim, and Gateman will create it if it doesn't exist.
gateman.allow('role').to('claim'); //for an existing role
You can also assign a claim to a role immediately after creating it
let role = await gateman.createRole("admin");
await gateman.allow("admin").to("delete");
//this provides every member of the admin role the claim to delete
Retracting claims from a role is very easy, you just need the rolename and claimname
await gateman.disallow('role').from('claim');
//Gateman does nothing if the role doesn't possess the claim
Checking if a Claim has been assigned to a Role can be done this way
let result = await gateman.role('rolename').can('claimname');
//result is true if the claim has been assigned, else it will be false
It is important to set up your User model to extend the HasRolesAndClaims class from the gateman package.
const mongoose = require('mongoose');
const hasRolesAndClaims = require('gatemanjs').hasRolesAndClaims(mongoose);
var UserSchema = mongoose.Schema({
name: String,
email: String
});
UserSchema.loadClass(hasRolesAndClaims);
module.exports = mongoose.model('User', UserSchema)
After setting up your user model, you can call gateman methods on your mongoose user model.
//Example
let user = await UserModel.findOne({name: "chioma"});
await user.allow("claim");
/*
The Gateman hasRolesAndClaims class is loaded into a valid mongoose model which means that the methods are only accessible to valid user objects.
*/
//Disallowing a user from performing a claim
let user = await UserModel.findOne({name: "chioma"});
await user.disallow("claim");
Before assigning a role to a user, make sure it has been created.
//Example
let user = await UserModel.findOne({name: "chioma"});
await user.assign("role");
/*
The Gateman hasRolesAndClaims class is loaded into a valid mongoose model which means that the methods are only accessible to valid user objects.
*/
//Retracting a role from a user
let user = await UserModel.findOne({name: "chioma"});
await user.retract("role");
Gateman provides an easy way of verifying if a user belongs to a role or can perform a claim
//To verify if a User belongs to a Role
let user = await User.findOne({name: "chioma"});
let userHasRole = await user.isA("role");
if (userHasRole){
//user belongs to role
}
//To verify if a User can perform a claim
let user = await User.findOne({name: "chioma"});
let userHasClaim = await user.can("claim");
if (userHasClaim){
//user can perform claim
}
Gateman provides an easy way of retrieving a User's roles and/or claims
//Returns a collection of Roles assigned to a User
let user = await User.findOne({name: "chioma"});
let roles = await user.getRolesForUser();
console.log(roles);
//Returns a collection of Claims a User can perform
let user = await User.findOne({name: "chioma"}, (err, user)=>{
let claims = await user.getClaimsForUser();
console.log(claims);
- Usage: Gateman methods
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
- Ositadinma Nwangwu - NwangwuOsitadinma
- Ibe Ogele - Ibesoft11
This project is licensed under the MIT License - see the LICENSE.md file for details
- This project was inspired by Joseph Silber's Bouncer
- Mongoose was used to build this