🚧

Prerequisites

Required SDK versions for Entitlement are:

React 6.0.25
Angular 6.17.0
Vue.js 3.0.17
Vanilla.js 6.175.0

Node.js 5.3.0

What are Roles?

Frontegg's role-based solution for managing users makes it easy to implement and assign roles, giving you the maximum ability to customize which users can access various parts of your application. Role-based access control is a common approach for restricting access to parts of an application to only authorized users.

A user's access to information and functionality in your application is defined by the roles assigned to the user. Every user has one or more roles. Each role is defined by the group of permissions assigned to that role. Each permission corresponds to the ability to do something in your application.

The way you design roles in Frontegg is intuitive and behaves as you would expect from any standard role-based system. We do, however, have a few unique features explained in our guides.

How to manage roles for your app

Roles exist in every environment, within your Entitlements section. Roles are linked to Permissions, thus granting users who are holding them their subset permissions.

Frontegg roles and defaults

By default, we've configured two preset roles including permissions— Admin and Read Only. You can use, edit, or delete them.

You can set roles and assign them to users. This action can happen in two different ways:

In the Backoffice - When you will add users to different accounts.

By your customer within the admin portal - when inviting new users. Users must assign the invited user a role.

766

Role Properties

PropertyDescription
NameThis property will be presented to all users when inviting others on the Frontegg portal within the Backoffice or when adding users to accounts in your app. Try to make it descriptive.
DescriptionThe description is intended to help you and your teammates understand the role internally.
KeyAn internal identifier that must be unique. As mentioned above, the JWT includes a ‘roles’ array, that contains the role keys associated with that user.
LevelA role level can refer to the level of authority or privilege associated with a specific role for a user. Usually, higher role levels have more permissions and access than lower role levels. Users can only apply roles (to other users) with levels lower than theirs.
Permissions listAn individual permission allows someone to perform a specific task, such as uploading a video or editing a profile. Essentially, each role contains a set of permissions assigned to it.
Assigned accountsThe role can be assigned to a specific account or all accounts in the environment.
IDEach role has a unique ID that is generated automatically upon role creation (see note*)

Roles table and actions

In the roles table, you can see all roles created by Frontegg (Admin and Read only roles) and by you (custom roles).

  1. Search bar - gives you the option to search for a specific role
  2. Filters - you can filter roles by levels
  3. Delete a role - use the three dots on the right side of each role line to delete it.

🚧

Delete a role

In the case of deleting a role, make sure there are no users without any roles.

Role Creation and Editing

Create a new role by clicking the "Add new role" button.

Create a new role

Create a new role

When creating a new role, note that you have a Key and Level fields. The Key field represents the identifying key that will be stored in the user's JWT and will be associated with the role if you wish to use it as an attribute, possibly for Feature Flagging. The Level field will indicate the level of this role and will allow the person holding it to invite or assign roles only to users with an equal or greater level than theirs.

On the Settings tab add the following details:

FieldDescription
Nameeach role must have a unique name.
Descriptionwe advise you to add a description that will help you manage your roles.
Keyadd a unique key, which will be used to identify the role.
Levela numeric input that helps you manage role hierarchy. Roles can only invite/assign roles with a level equal to or greater than their own role level.
Default roleWhen you or other teammates on the Frontegg portal will add users to accounts, you will be able to set default roles as ‘suggested’ in the backoffice. Please note, this can be reversed when adding new users.
Select accountas default, a role is set to all accounts in an environment, but, you can decide to attach it to a specific account. In that way, just one account in that environment will be able to see and use the role. Once you click on the Save button, you won’t be able to reverse the decision. (You will still be able to delete the role and change the settings though)

🚧

Default role

Make sure you have at least one role you include as "Default". This role will be added to a user when signing up.

Assigning permissions to roles:

  1. Go to the Roles tab and click Assign Permissions
  2. Mark the permissions you would like to add to this role
  3. Click “Assign permissions”
  4. Click ‘Save’ to add the role to the role table

📘

When should you add permissions to roles?

A role can be saved without permissions. Those can be added later on.

Edit existing roles

In order to go back and edit an existing role, click on the role line in the table and edit its settings.

How does roles work in Frontegg?

When Frontegg generates a user/API M2M access token (JWT), it includes a ‘roles’ array which contains the role keys associated with this user, and also a ‘permissions’ array with all the permission keys contained in those roles.

The Frontegg backend SDKs can verify the JWT and enforce roles and permissions for you, and you can specify the ‘permissions’ and/or ‘roles’ that are required for a certain operation. See more details on the implementation here.

Wrapping it all up - Who uses roles and where?

  1. Setting up roles and permissions on each environment (this guide explains how you can do that)
  2. Adding/ editing roles for specific users within the backoffice
  3. Inviting users to an account within the backoffice

Your users can invite others and attach roles via admin portal

Getting Started with Roles

  1. Ensure you’ve enabled the roles and permission option under the Entitlements → Roles → Settings → Role-based authorization.
  1. In case you created custom roles and added custom permissions, make sure you’ve added them to your code.
  2. Create roles and permissions in one of the testing environments before moving them to Production.
    Add a new test user with that role and validate the performance on your end.
  3. Move the roles and Permissions to Production

Additional resources

APIs related to Roles

  1. Get roles
  2. Create roles
  3. Delete role
  4. Update role
  5. Set multiple permissions to a role

See next