No Packages, Mate

    @rocketseat/adonis-acl

    1.2.2 • Public • Published

    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:
    $ adonis install @rocketseat/adonis-acl
    1. Register ACL providers inside the your start/app.js file.
    const providers = [
      ...
      '@rocketseat/adonis-acl/providers/AclProvider',
      ...
    ]
    
    const aceProviders = [
      ...
      '@rocketseat/adonis-acl/providers/CommandsProvider',
      ...
    ]
    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',
      acl: 'Adonis/Acl/Acl',
      scope: 'Adonis/Acl/Scope'
      ...
    }

    For using in views

    const globalMiddleware = [
      ...
      'Adonis/Acl/Init'
      ...
    ]
    1. Publish the package migrations to your application and run these with adonis migration:run.
    $ adonis 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();

    Protect Routes

    Syntax:

    and - administrator and moderator

    or - administrator or moderator

    not (!) - administrator and !moderator

    // check roles
    Route.get("/users").middleware([
      "auth:jwt",
      "is:(administrator or moderator) and !customer"
    ]);
    
    // check permissions
    Route.get("/posts").middleware(["auth:jwt", "can:read_posts"]);
    
    // check roles and permissions
    Route.put("/posts").middleware(["auth:jwt", "acl:admin or update_posts"]);
    
    // scopes (using permissions table for scopes)
    Route.get("/posts").middleware(["auth:jwt", "scope:posts.*"]);

    The acl middleware is used to verify both a role and a permission at the same time, but for it to work properly it is necessary that a role and a permission doesn't share the same name.

    Vow trait

    adonis-acl has a trait to make it easy to use it while testing with adonis-vow. To enable the addRoles and addPermissions methods, you need to add the trait Acl/Client.

    The arguments must be your roles or permissions.

    const [admin, moderator] = await Role.all();
    addRole(admin, moderator);
    const [create, read, update, del] = await Permission.all();
    addPermission(create, read, update, del);

    Here's an example of how to use it inside a test:

    const { test, trait } = use("Test/Suite")("Awesome test");
    
    trait("Test/ApiClient");
    trait("Auth/Client");
    trait("Acl/Client");
    
    test("awesome some test", async ({ client }) => {
      const role = await Role.find(1);
      const permission = await Permission.find(1);
      const user = await User.find(1);
    
      const response = await client
        .put("/posts/1")
        .loginVia(user)
        .addRoles(role)
        .addPermissions(permission)
        .end();
    });

    Both addRoles and addPermissions inject roles and permissions on the user that was passed by loginVia method, so it is vital to call them after loginVia as seen on the example above.

    It is also crucial that trait("Auth/Client") is called before trait("Acl/Client").

    Using commands

    Command Description Options
    adonis acl:setup Publish the package migrations to your application
    adonis acl:role <slug> [name][description] Make a new role --permissions=<slug list of permissions separated by comma> Attach permissions to the role
    adonis acl:permissions <slug> [name][description] Make a new permission or updates the name and description if the slug was found

    Using in Views

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

    or

    @loggedIn
      @can('create_posts or 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.

    Keywords

    Install

    npm i @rocketseat/adonis-acl

    DownloadsWeekly Downloads

    92

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    71.1 kB

    Total Files

    38

    Last publish

    Collaborators

    • dieegosf
    • higoribeiro
    • thepellizzetti