An Authorization library for Sequelize.js.
Fast, Easy, Roles & Permissions based Authorization.
- Fluent, easy to use semantic API.
- Assign multiple Roles, Permissions to User.
- Super FAST cache based permission resolution system.
- Listen for Events related to authorization. Check Events
- No dependency on Node-acl.
to know more see documentation.
let me know how you feela about this library:
- twitter : @impankajv1
- SequelizeGuard
After installation you can do stuff like
- Setup
//Assign Role to a user.
user.assignRole('admin');
//assign permission to a role.
guard.init().allow('admin').to(['view', 'edit']).on('blog').commit();
//or if you like one liners
guard.allow('admin', ['view', 'edit'], 'blog');- Authorize
by permission
//view blog
user.can('view blog');
//All Actions on blog
user.can('* blog');
//view All Resources, eg. analyst
user.can('view *');
//All Action on All Resources, superadmin
user.can('*');or by Role
//check if user is editor
user.isA('editor');
//use isAn where you require
user.isAn('admin');
//use isAnyOf to check either of roles
user.isAnyOf(['admin', 'moderator']);npm i sequelize-guardor
yarn add sequelize-guardMake sure, Sequelize is setup in your project. If not, follow Sequelize Getting Started first.
sequelize-guard will automatically register and sync needed schemas.
Or you can use following code in a migration file
var SequelizeGuard = require('sequelize-guard');
module.exports = {
up: (queryInterface, Sequelize) => {
return SequelizeGuard.migration.up(queryInterface, Sequelize, options);
},
down: (queryInterface, Sequelize) => {
return SequelizeGuard.migration.down(queryInterface, Sequelize, options);
},
};Create sequelize object with your database configuration.
For example we have used default Sequelize setup file for models.
//models/index.js
let sequelize;
if (config.use_env_variable) {
sequelize = new Sequelize(process.env[config.use_env_variable], config);
} else {
sequelize = new Sequelize( ... );
}Initialize SequelizeGuard object after you have already initialized your models.
//Import library
var SequelizeGuard = require('sequelize-guard');
...
//initialize Sequelize
...
//initialize SequelizeGuard & add to db for global use
var guard = new SequelizeGuard(sequelize, options);
db.sequelize = sequelize;
db.Sequelize = Sequelize;
db.guard = guard; // <---------- Add this line
module.exports = db;Please Note:
- Make sure you pass same same options to migration and SequelizeGuard constructor,
- If you have your own User Model implemented, make sure you pass it during initialization,
- not required for migrations.
//defaults
{
prefix : 'guard_',
primaryKey : 'id',
timestamps : false,
paranoid : false,
sync: true,
debug: false,
userModel: null,
userPk : 'id', //User Primary Key
safeGuardDeletes : true,
userCache: true,
userCacheTime: 60, // 60
}- prefix : custom prefix for for all tables
- primaryKey : custom primary key for all guard tables (to be implemented) ,
- timestamps : (bool | false), add timestamps to table
- paranoid : (bool | false), soft deletes
- sync: (bool | true), if set to true, database tables will be created without migrations
- debug: (bool | false), print database queries to console.
- userModel: (Sequelize Model | null), custom used model you want to use, instead of default User Model.
- userPk : (string | 'id' ), Primary key for User Model, in case your custom model has primaryKey other than 'id'.
- safeGuardDeletes : (bool | true), if set to true, role or permissions can't be deleted as long as they are associated with any other data. To remove you must break all other associations (to be tested).
- userCache : (bool | true), roles of user will be cached, this will allow faster permission resolution and less database connections.
- userCacheTime : (int | 60), time for which roles of user will be cached (in seconds), this number should be inversely proportional to your user traffic.
- GuardControl is API layer over SequelizeGuard.
- Makes API calls chainable, which means you can call them in whichever order you prefer. [ exception :
commit()].
We are going to use same instance guard of SequelizeGuard we created during setup.
It's best to learn from examples. So here we will take a basic example.
guard.init().allow('admin').to(['view', 'edit']).on('blog').commit();(There's a one liner alternative available. Read below in SequelizeAPI)
Looks natural and easy right? Let's break the above example.
1. init()
To initialize an GuardControl call init() method on guard instance.
This function returns a brand new instance of GuardControl.
2. allow()
parameter : Role (string)
- Pass name of role for which you are making control statement.
- Currently only supports one role at time. (Planning on allowing multiple roles soon).
Note: If you call this multiple times, whatever you passed most recently is considered.
3. to()
parameter : Action(s) (string | array)
- accepts action as string or array of string.
- eg. view, edit, update, delete, wildcard (*)
4. on()
parameter : Resource(s) (string | array)
- pass name of resources as string or array of strings.
- eg. blog, post, image, article, wildcard(*)
5. commit()
Asynchronous call which saves all the data provided in database, using magic of SequelizeGuard and Sequelize.
- If permission is already created before, same permission is used.
- If Role is already created same role is assigned permission given.
Returns : object with properties roles, permission. All the roles and permissions specified (created or old) by this GuardControl statement are returned.
SequelizeGuard adds some api calls to User Model that you provide in options. So you can assign roles straight from your user object that is logged in.
- user.assignRole
- user.assignRoles
- user.rmAssignedRoles
for handling permissions
- createPerms
- createPermsBulk
- findPerms
for handling roles
- makeRole
- makeRoles
- deleteRoles
- allRoles
- getRole
- findRoles
for associations between user/role/permission
- allow : GuardControl in one line
- addPermsToRole
- rmPermsFromRole
- assignRoles
- rmAssignedRoles
For More information check SequelizeGuard API Reference.
parameter : 'action resource' (string) returns : bool
Pass permission you are testing for as follows. returns true if allowed.
//view blogs
user.can('view blogs');
//All Actions on blogs
user.can('* blogs');
//view All Resources, eg. analyst
user.can('view *');
//All Action on All Resources, superadmin
user.can('*');You can use following methods to have perform role based authorization.
- user.isAllOf(roles)
- user.isAnyOf(roles)
- user.isA(role)
- user.isAn(role)
For More information check SequelizeGuard API Reference.
You can listen to following events. They can be helpful for logging or updating user cache
- onRolesCreated : with created roles
- onRolesDeleted : with data of deleted roles
- onPermsCreated : with created permissions
- onPermsAddedToRole : with data after permissions added
- onPermsRemovedFromRole : with data after permissions are removed
- Make seeders better, see branch dev-seeder for progress.
- Implement "allow except" kind of permissions.
- Role priority, which will allow to do things like
user.atleast('admin')user.atmost('admin')
- Spaties's Laravel-permission, Authorization Library for Laravel.
- Node-ACL for Node.js
- Node-ACL is versatile library which has support for most ORMs. I actually tried to use that before writing this, but somehow wasn't feeling the power or freedom I wanted. But it is quite popular and mostly used.
For docs or tests or even code, feel free to send Pull Requests.
Feel free to create issues.
The MIT License (MIT). Please see License File for more information.