Roles
Prerequisites
Required SDK versions Entitlement roles are:
React 6.0.25
Angular 6.17.0
Vue.js 3.0.17
Vanilla.js 6.175.0Node.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.
Role Properties
| Property | Description |
|---|---|
| Name | This 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. |
| Description | The description is intended to help you and your teammates understand the role internally. |
| Key | An internal identifier that must be unique. As mentioned above, the JWT includes a ‘roles’ array, that contains the role keys associated with that user. |
| Level | A 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 list | An 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 accounts | The role can be assigned to a specific account or all accounts in the environment. |
| ID | Each 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).
- Search bar - gives you the option to search for a specific role
- Filters - you can filter roles by levels
- 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
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:
| Field | Description |
|---|---|
| Name | each role must have a unique name. |
| Description | we advise you to add a description that will help you manage your roles. |
| Key | add a unique key, which will be used to identify the role. |
| Level | a 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 role | When 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 account | as 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:
- Go to the Roles tab and click Assign Permissions
- Mark the permissions you would like to add to this role
- Click “Assign permissions”
- 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
To go back and edit an existing role, click on the role line in the table and edit its settings.
Custom Roles
You can let your account create their own custom roles. Go to custom roles to learn more.
How do roles work in Frontegg?
When Frontegg generates a user/API M2M access token (JWT), it includes a ‘roles’ array containing the role keys associated with this user and 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?
Getting Started with Roles
- Ensure you’ve enabled the roles and permission option under the Entitlements → Roles → Settings → Role-based authorization.
- If you created custom roles and custom permissions, make sure you’ve added them to your code.
- 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. - Move the roles and Permissions to Production
Additional resources
APIs related to Roles
See next
Updated about 2 months ago