Skip to content

Latest commit

 

History

History
393 lines (303 loc) · 8.09 KB

README.md

File metadata and controls

393 lines (303 loc) · 8.09 KB
Raw

!!! Maintainer Needed !!!

I currently don't have the resources to maintain this project. If someone is willing to put in the time to do it, I'm willing to assign the necessary privileges to that person. If you're willing to do this, reply on issue or send me email.

Adonis ACL

Adonis ACL adds role based permissions to built in Auth System of Adonis Framework.

NPM Version GitHub license Build Status Coverage Status

Installation

  1. Add package:
$ npm i adonis-acl --save

or

$ yarn add adonis-acl
  1. Register ACL providers inside the your start/app.js file.
const providers = [
  ...
  'adonis-acl/providers/AclProvider',
  ...
]

const aceProviders = [
  ...
  'adonis-acl/providers/CommandsProvider',
  ...
]
  1. Setting up aliases inside start/app.js file.
const aliases = {
  ...
  Role: 'Adonis/Acl/Role',
  Permission: 'Adonis/Acl/Permission',
  ...
}
  1. Setting up traits to User model.
class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasRole',
      '@provider:Adonis/Acl/HasPermission'
    ]
  }
  ...
}
  1. Setting up middlewares inside start/kernel.js file.
const namedMiddleware = {
  ...
  is: 'Adonis/Acl/Is',
  can: 'Adonis/Acl/Can',
  ...
}

For using in views

const globalMiddleware = [
  ...
  'Adonis/Acl/Init'
  ...
]
  1. Publish the package migrations to your application and run these with ./ace migrations:run.
$ ./ace acl:setup

Working With Roles

Create Role

Lets create your first roles.

const roleAdmin = new Role()
roleAdmin.name = 'Administrator'
roleAdmin.slug = 'administrator'
roleAdmin.description = 'manage administration privileges'
await roleAdmin.save()

const roleModerator = new Role()
roleModerator.name = 'Moderator'
roleModerator.slug = 'moderator'
roleModerator.description = 'manage moderator privileges'
await roleModerator.save()

Before, You should do first, use the HasRole trait in Your User Model.

class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasRole'
    ]
  }
  ...
}

Attach Role(s) To User

const user = await User.find(1)
await user.roles().attach([roleAdmin.id, roleModerator.id])

Detach Role(s) From User

const user = await User.find(1)
await user.roles().detach([roleAdmin.id])

Get User Roles

Get roles assigned to a user.

const user = await User.first()
const roles = await user.getRoles() // ['administrator', 'moderator']

Working With Permissions

Create Role Permissions

const createUsersPermission = new Permission()
createUsersPermission.slug = 'create_users'
createUsersPermission.name = 'Create Users'
createUsersPermission.description = 'create users permission'
await createUsersPermission.save()

const updateUsersPermission = new Permission()
updateUsersPermission.slug = 'update_users'
updateUsersPermission.name = 'Update Users'
updateUsersPermission.description = 'update users permission'
await updateUsersPermission.save()

const deleteUsersPermission = new Permission()
deleteUsersPermission.slug = 'delete_users'
deleteUsersPermission.name = 'Delete Users'
deleteUsersPermission.description = 'delete users permission'
await deleteUsersPermission.save()

const readUsersPermission = new Permission()
readUsersPermission.slug = 'read_users'
readUsersPermission.name = 'Read Users'
readUsersPermission.description = 'read users permission'
await readUsersPermission.save()

Before, You should do first, use the HasPermission trait in Your User Model.

class User extends Model {
  ...
  static get traits () {
    return [
      '@provider:Adonis/Acl/HasPermission'
    ]
  }
  ...
}

Attach Permissions to Role

const roleAdmin = await Role.find(1)
await roleAdmin.permissions().attach([
  createUsersPermission.id,
  updateUsersPermission.id,
  deleteUsersPermission.is,
  readUsersPermission.id
])

Detach Permissions from Role

const roleAdmin = await Role.find(1)
await roleAdmin.permissions().detach([
  createUsersPermission.id,
  updateUsersPermission.id,
  deleteUsersPermission.is,
  readUsersPermission.id
])

Get User Permissions

Get permissions assigned to a role.

const roleAdmin = await Role.find(1)
// ['create_users', 'update_users', 'delete_users', 'read_users']
await roleAdmin.getPermissions()

or

const roleAdmin = await Role.find(1)
// collection of permissions
await roleAdmin.permissions().fetch()

Working With Permissions

Create User Permissions

const createUsersPermission = new Permission()
createUsersPermission.slug = 'create_users'
createUsersPermission.name = 'Create Users'
createUsersPermission.description = 'create users permission'
await createUsersPermission.save()

const updateUsersPermission = new Permission()
updateUsersPermission.slug = 'update_users'
updateUsersPermission.name = 'Update Users'
updateUsersPermission.description = 'update users permission'
await updateUsersPermission.save()

const deleteUsersPermission = new Permission()
deleteUsersPermission.slug = 'delete_users'
deleteUsersPermission.name = 'Delete Users'
deleteUsersPermission.description = 'delete users permission'
await deleteUsersPermission.save()

const readUsersPermission = new Permission()
readUsersPermission.slug = 'read_users'
readUsersPermission.name = 'Read Users'
readUsersPermission.description = 'read users permission'
await readUsersPermission.save()

Before, You should do first, use the HasPermission trait in Your User Model.

class User extends Model {
  ...
  static get traits () {
    return [
      'Adonis/Acl/HasPermission'
    ]
  }
  ...
}

Attach Permissions to User

const user = await User.find(1)
await user.permissions().attach([
  createUsersPermission.id,
  updateUsersPermission.id,
  deleteUsersPermission.is,
  readUsersPermission.id
])

Detach Permissions from User

const user = await User.find(1)
await user.permissions().detach([
  createUsersPermission.id,
  updateUsersPermission.id,
  deleteUsersPermission.is,
  readUsersPermission.id
])

Get User Permissions

Get permissions assigned to a role.

const user = await User.find(1)
// ['create_users', 'update_users', 'delete_users', 'read_users']
await user.getPermissions()

or

const user = await User.find(1)
// collection of permissions
await user.permissions().fetch()

Protect Routes

Syntax:

and (&&) - administrator && moderator

or (||) - administrator || moderator

not (!) - administrator && !moderator

// check roles
Route
  .get('/users')
  .middleware(['auth:jwt', 'is:(administrator || moderator) && !customer'])

// check permissions
Route
  .get('/posts')
  .middleware(['auth:jwt', 'can:read_posts'])

// scopes (using permissions table for scopes)
Route
  .get('/posts')
  .middleware(['auth:jwt', 'scope:posts.*'])

Using in Views

@loggedIn
  @is('administrator')
    <h2>Protected partial</h2>
  @endis
@endloggedIn

or

@loggedIn
  @can('create_posts && delete_posts')
    <h2>Protected partial</h2>
  @endcan
@endloggedIn

or

@loggedIn
  @scope('posts.create', 'posts.delete')
    <h2>Protected partial</h2>
  @endscope
@endloggedIn

Credits

Support

Having trouble? Open an issue!

License

The MIT License (MIT). Please see License File for more information.