Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/enniel/adonis-acl
demo app: https://github.com/enniel/adonis-acl-blog-demo
https://github.com/enniel/adonis-acl
acl adonis adonis-framework adonisjs permissions roles
Last synced: 7 days ago
JSON representation
demo app: https://github.com/enniel/adonis-acl-blog-demo
- Host: GitHub
- URL: https://github.com/enniel/adonis-acl
- Owner: enniel
- License: mit
- Created: 2017-05-28T20:46:16.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-08-05T12:04:50.000Z (over 3 years ago)
- Last Synced: 2024-10-11T13:49:17.043Z (about 1 month ago)
- Topics: acl, adonis, adonis-framework, adonisjs, permissions, roles
- Language: JavaScript
- Homepage:
- Size: 57.6 KB
- Stars: 203
- Watchers: 9
- Forks: 50
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-adonisjs-packages - Adonis ACL - Adds role based permissions. (Authentication & Authorization)
README
## !!! 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](https://github.com/enniel/adonis-acl/issues/49) or send me [email](mailto:[email protected]).
# Adonis ACL
Adonis ACL adds role based permissions to built in [Auth System](https://github.com/adonisjs/adonis-auth) of [Adonis Framework](https://github.com/adonisjs/adonis-framework).
[](https://npmjs.org/package/adonis-acl)
[](https://github.com/enniel/adonis-acl/blob/master/LICENSE.md)
[](https://travis-ci.org/enniel/adonis-acl)
[](https://coveralls.io/github/enniel/adonis-acl?branch=master)
## Installation
1. Add package:
```bash
$ npm i adonis-acl --save
```
or
```bash
$ yarn add adonis-acl
```
2. Register ACL providers inside the your start/app.js file.
```js
const providers = [
...
'adonis-acl/providers/AclProvider',
...
]
const aceProviders = [
...
'adonis-acl/providers/CommandsProvider',
...
]
```
3. Setting up aliases inside `start/app.js` file.
```js
const aliases = {
...
Role: 'Adonis/Acl/Role',
Permission: 'Adonis/Acl/Permission',
...
}
```
4. Setting up traits to `User` model.
```js
class User extends Model {
...
static get traits () {
return [
'@provider:Adonis/Acl/HasRole',
'@provider:Adonis/Acl/HasPermission'
]
}
...
}
```
5. Setting up middlewares inside `start/kernel.js` file.
```js
const namedMiddleware = {
...
is: 'Adonis/Acl/Is',
can: 'Adonis/Acl/Can',
...
}
```
For using in views
```js
const globalMiddleware = [
...
'Adonis/Acl/Init'
...
]
```
6. Publish the package migrations to your application and run these with `./ace migrations:run`.
```bash
$ ./ace acl:setup
```
## Working With Roles
### Create Role
Lets create your first roles.
```js
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.
```js
class User extends Model {
...
static get traits () {
return [
'@provider:Adonis/Acl/HasRole'
]
}
...
}
```
### Attach Role(s) To User
```js
const user = await User.find(1)
await user.roles().attach([roleAdmin.id, roleModerator.id])
```
### Detach Role(s) From User
```js
const user = await User.find(1)
await user.roles().detach([roleAdmin.id])
```
### Get User Roles
Get roles assigned to a user.
```js
const user = await User.first()
const roles = await user.getRoles() // ['administrator', 'moderator']
```
## Working With Permissions
### Create Role Permissions
```js
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.
```js
class User extends Model {
...
static get traits () {
return [
'@provider:Adonis/Acl/HasPermission'
]
}
...
}
```
### Attach Permissions to Role
```js
const roleAdmin = await Role.find(1)
await roleAdmin.permissions().attach([
createUsersPermission.id,
updateUsersPermission.id,
deleteUsersPermission.is,
readUsersPermission.id
])
```
### Detach Permissions from Role
```js
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.
```js
const roleAdmin = await Role.find(1)
// ['create_users', 'update_users', 'delete_users', 'read_users']
await roleAdmin.getPermissions()
```
or
```js
const roleAdmin = await Role.find(1)
// collection of permissions
await roleAdmin.permissions().fetch()
```
## Working With Permissions
### Create User Permissions
```js
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.
```js
class User extends Model {
...
static get traits () {
return [
'Adonis/Acl/HasPermission'
]
}
...
}
```
### Attach Permissions to User
```js
const user = await User.find(1)
await user.permissions().attach([
createUsersPermission.id,
updateUsersPermission.id,
deleteUsersPermission.is,
readUsersPermission.id
])
```
### Detach Permissions from User
```js
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.
```js
const user = await User.find(1)
// ['create_users', 'update_users', 'delete_users', 'read_users']
await user.getPermissions()
```
or
```js
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
```js
// 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')
Protected partial
@endis
@endloggedIn
```
or
```
@loggedIn
@can('create_posts && delete_posts')
Protected partial
@endcan
@endloggedIn
```
or
```
@loggedIn
@scope('posts.create', 'posts.delete')
Protected partial
@endscope
@endloggedIn
```
## Credits
- [Evgeni Razumov](https://github.com/enniel)
## Support
Having trouble? [Open an issue](https://github.com/enniel/adonis-acl/issues/new)!
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.