adonis-acl

Adonis ACL

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

Installation

• Add package:

$ npm i adonis-acl --save

or

$ yarn add adonis-acl

• Register ACL providers inside the your start/app.js file.

const providers = [
  ...
  'adonis-acl/providers/AclProvider',
  ...
]

const aceProviders = [
  ...
  'adonis-acl/providers/CommandsProvider',
  ...
]

• Setting up aliases inside start/app.js file.

const aliases = {
  ...
  Role: 'Adonis/Acl/Role',
  Permission: 'Adonis/Acl/Permission',
  ...
}

• Setting up traits to User model.

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

• 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'
  ...
]

• 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

• Evgeni Razumov

Support

Having trouble? Open an issue!

License

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