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 a role is a named set of abilities (permissions) by which a specific group of users is identified. So for example USER or ANONYMOUS would be roles and not permissions. We can represent our USER role as a group of permissions that the role should be able to perform. For example: 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 PermRoleStore that exposes defineRole allowing to define custom roles used by users in your application.

[...]

PermRoleStore
  .defineRole('ROLE_NAME', ['permissionNameA', 'permissionNameB', 'permissionNameC', ...])
  
PermRoleStore
  .defineRole('ROLE_NAME', /*@ngInject*/ function (roleName, transitionProperties) {
        [...]
      });
  });

The main difference 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 PermPermissionStore method definePermission. If not on first state or route check PermAuthorisation 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 are injected with any angular services. There are 2 local injectables available 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:

PermRoleStore
  // 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']);  
  
PermRoleStore    
  // Or use your own function/service to validate role
  .defineRole('USER', /*@ngInject*/ function (Session) {        
    return Session.checkSession();
  });

Multiple roles

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

PermRoleStore    
  // Or use your own function/service to validate role
  .defineManyRoles({
    'AUTHORIZED': /* @ngInject*/ function (Session) { 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:

PermRoleStore.clearStore();

Alternatively you can use removeRoleDefinition to delete defined role manually:

PermRoleStore.removeRoleDefinition('USER');

Getting all roles definitions

To get specific role use method getRoleDefinition:

var role = PermRoleStore.getRoleDefinition('roleName');

And to get all roles form PermRoleStore use method getStore:

var roles = PermRoleStore.getStore();

---

Next to read: 👉 Controlling access in views