Managing roles

Before start

Make sure you are familiar with:

• Managing permissions

Overview

1. Introduction
2. Defining roles
3. Individual roles
4. Multiple roles
5. Removing roles
6. Getting all role definitions

Introduction

By definition role is named set of abilities (permissions) by which specific group of users is identified. So USER and ANONYMOUS are roles not permissions. We can represent our USER as group of permissions that identifies his like: listArticles, editArticles and other custom server/browser validated privileges.

💡 Note
It's a good convention to name roles with UPPER_CASE, so roles like ACCOUNTANT or ADMIN are easier to distinguish from permissions.

Defining roles

Individual roles

Similarly to permissions we are gonna use here RoleStore that exposes defineRole allowing to define custom roles used by users in your application.

[...]

RoleStore
  .defineRole('ROLE_NAME', ['permissionNameA', 'permissionNameB', 'permissionNameC', ...])
  
RoleStore
  .defineRole('ROLE_NAME', function (roleName, transitionProperties) {
        [...]
      });
  });

The main deference is that Role definition accepts either array of permissions names that identify role or validation function used similarly like in permissions.

💡 Note
When defining role with array of permission names, make sure that your permissions will be defined via PermissionStore method definePermission. If not on first state or route check Authorisation service will call for their validity, and if they won't be present it might reject authorization, as an effect of not having role.

Validation function accepts two parameters that can be used to implement more complex validation logic.

Parameter	Description
roleName	String representing name of checked role
transitionProperties	TransitionProperties object storing properties of transited states/routes

It also have to return one of values to properly represent results:

Validation result	Returned value
Valid	[true|$q.resolve()]
Invalid	[false|$q.reject()]

💡 Note
You can not define roles on config stage of modules.

Usage of defineRole is very similar to definePermission:

RoleStore
  // Permission array validated role
  // Library will internally validate if 'listEvents' and 'editEvents' permissions are valid when checking if role is valid   
  .defineRole('ADMIN', ['listEvents', 'editEvents']);  
  
RoleStore    
  // Or use your own function/service to validate role
  .defineRole('USER', function () {        
    return Session.checkSession();
  });

Multiple roles

Service RoleStore allows you define multiple roles with defineManyRoles method. This method accepts Object containing keys as a role names and corresponding validators as values.

RoleStore    
  // Or use your own function/service to validate role
  .defineManyRoles({
    'AUTHORIZED': function () {        
      return Session.checkSession();
    }),
    `USER`: ['canReadInvoices']
    'ADMIN': ['canReadInvoices','canEditInvoices','canUploadImages']
  });

💡 Note
This method is highly effective when you fetch role definitions form server together with permissions.

Removing roles

To remove all roles use clearStore method:

RoleStore.clearStore();

Alternatively you can use removeRoleDefinition to delete defined role manually:

RoleStore.removeRoleDefinition('USER');

Getting all roles definitions

To get all roles form RoleStore use method getStore:

var roles = RoleStore.getStore();

---

Next to read: 👉 Controlling access in views