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 roles

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 RolesService that exposes addRole allowing to define custom roles used by users in your application.

[...]

NgxRolesService
  .addRole('ROLE_NAME', ['permissionNameA', 'permissionNameB', 'permissionNameC', ...])
  
NgxRolesService.addRole('Guest', () => {
      return this.sessionService.checkSession().toPromise();
  }); 

NgxRolesService.addRole('Guest', () => {
      return true;
  }); 

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	Array or validation function

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

Validation result	Returned value
Valid	[true|Promise.resolve() but it should not resolve false]
Invalid	[false|Promise.reject() or Promise.resolve(false)]

Note: Right now to make request to the backend it only supports promises Note: If at least one of request fulfils it will show the component

Usage of addRole is very similar to addPermissions:

NgxRolesService
  // Library will internally validate if 'listEvents' and 'editEvents' permissions are valid when checking if role is valid   
  .addRole('ADMIN', ['listEvents', 'editEvents']);  
  
NgxRolesService.addRole('Guest', () => {
      return this.sessionService.checkSession().toPromise();
  });  
  

Multiple roles

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

NgxRolesService    
  // Or use your own function/service to validate role
  .addRoles({
    'USER': ['canReadInvoices'],
    'ADMIN': ['canReadInvoices','canEditInvoices','canUploadImages'],
    'GUEST': () => {
        return this.sessionService.checkSessions().toPromise();
    }
  });

💡 Note

Removing roles

To remove all roles use flushRoles method:

NgxRolesService.flushRoles();

Alternatively you can use removeRole to delete defined role manually:

NgxRolesService.removeRole('USER');

Getting all roles

To get specific role use method getRole:

let role = NgxRolesService.getRole('roleName');

And to get all roles form NgxRolesService use method getRoles or use Observable roles$:

let roles = NgxRolesService.getRoles();

NgxRolesService.roles$.subscribe((data) => {
    console.log(data);
})