Admin & Admin Group Permissions

The goal of this page is to explain how the Admin and AdminGroup permission features work. To best understand these concepts see these schema files from the project:

• /schema/Admin.js
• /schema/AdminGroup.js

Group Memberships

Admins can be members of zero or many Admin Groups. You can change an Admin's group memberships by going to their details page /admin/administrators/:id/.

Checking for Group Membership

The instance method Admin#isMemberOf(groupId) is available to you during request logic. You can use this to check if an Admin is a member of a group like so:

if (req.user.roles.admin.isMemberOf('root')) {
  //yes, is a member of 'root'
}

You can see us using this out of the box in /views/admin/users/index.js to validate if a user can link Users documents to Admin documents.

workflow.on('validate', function() {
  if (!req.user.roles.admin.isMemberOf('root')) {
    workflow.outcome.errors.push('You may not link users to admins.');
    return workflow.emit('response');
  }
  ...

Permissions

Both the Admin and the AdminGroup schemas have a field called permissions. These fields are both defined like so:

...
permissions: [{ name: String, permit: Boolean }],
...

As you can see, these are just simple lists of permission names and true/false values representing if that Admin or Admin Group is permitted to use that permission.

Checking for Permission

The instance method Admin#hasPermissionTo(something) is available to you during request logic. You can use this to check if a member is permitted to do something by permission name.

We first check if any of the Admin's group memberships permit this and then we check if that Admin has a specific rule set for the permission. This allows us to define granular permissions at the Admin level that override the group's permissions (either true or false).

if (req.user.roles.admin.hasPermissionTo('DELETE_NOTES')) {
  //yes, you may delete notes
}
else {
  //no, you may not delete notes
}

Example: Let's say we have an Admin Group called Support and we let everyone in that group delete notes. If we have an Admin that we want to be in that group, but we don't want them to delete notes, all we need to do is define the 'DELETE_NOTES' permission for them and set it to false. Or we can grant permission to specific Admins without needing to add them to an entire group.

Related Reading

You should also familiarize yourself with the concepts of Users, Roles & Groups.

Use the Force

I hope this was helpful. If you have questions or think this page should be expanded please contribute by opening an issue or updating this page.