Roles and Permissions
Roles and Permissions allow users within the Form.io platform to be granted certain permissions to perform certain actions and have access to forms and submissions within a project.
Roles
Roles are a way of granting a group of users assigned to that role access to perform certain tasks as well as have access to forms or submissions within a project. Each project can have an unlimited number of Roles, and each role can be created and labeled dynamically. These Roles are assigned to Permissions to achieve this functionality. Click Here to read more about the Permission system.
Every Role within a Project has a unique ID specific to the project in which it is created. which can ONLY be granted to users within that project. As a security constraint, it is not possible to grant a user within a separate project a role that belongs to another project, nor can a role be used to grant permissions outside of a Project context. This allows every project role to be "sandboxed" to that specific project.
Default Roles
When a new Project is created, (4) Roles are created by default:
Anonymous: This role is reserved for unauthenticated users that need permission to interact with a Form. A common use case for the Anonymous Role could be a Login / Registration form or a company survey form where the application does not know who the user is. The Anonymous Role can not be deleted from a Project.
Everyone: Represents the default access level that applies to all users, including those who are not authenticated or logged in (anonymous). This role is often used to define the baseline permissions for accessing forms and data within the platform. In other words, when the Everyone role as assigned to a permission, all roles within the Project are applied to that permission. The ID will always be 00000000000000000000000 and is not an actual role within the MongoDB database. This Role can not be deleted from a Project.
Administrator & Authenticated: There is nothing inherently special about these two Roles and are automatically created with the Project to provide a starting point for different roles a userbase might carry for an application workflow. For example, a logged-in user with the Authenticated role may be allowed to submit and view their submission data for Form A, but they won't have access rights to delete. A user with the Administrator role would typically have full CRUD (create, read, update, delete) permissions for the Form and Submission data.
Users can create as many roles as needed to align with their application requirements. All roles can be modified and deleted aside from the Anonymous and Everyone roles.
Creating and Configuring Roles
To create and manage Roles, click the Access tab located within the left-hand sidebar of your application. Additional Roles can be defined and added to a project at any time.
Create a new role by clicking the +New Role button, delete a Role by selecting the Trash Icon, or edit a Role name and description by selecting the Edit button.
When a new Role is created a unique MongoDB ID will be assigned to it by default. You can find this ID by selecting a Role within your project and viewing the URL within your browser. It will look something like this:
When a Resource is accessed by a User, and the User has a Role assigned to them with permissions to complete an operation they are attempting, the operation will be granted. If no Roles are defined to permissions on a given Resource, only the owner of the Resource or the Application itself will have access to that Resource.
By default, the creator of a Project will have access to every Resource associated within the Application. To receive ownership of a Resource, that Resource must be created with the “Create Own” Permission, which will assign the User initiating the request to become its owner. Additionally, a user can be defined as the owner of a Resource if they are specified as such during a Create All operation.
How Are Roles Assigned?
Form and Application authorization access is determined by the user's role. During the Authorization process, the User is handed a JWT Token which contains the User's unique ID. This ID is then used to look up the authenticating User's Role. The MongoDB Role ID is then saved to the user object.
Roles are assigned in a variety of ways depending on the Authentication Method of the application. With commonly used authentication methods like OAuth or SAML, the provider token is converted to an equivalent JWT token, and the provider Role is then mapped to a Form.io role. After authentication has been completed, and a Role has been assigned to a User, a typical user object within Form.io may look like the following. Take note of the Role ID in line 6.
Permissions
Roles are allocated to Permissions which are what govern user access and interaction with forms, submission data, and the Form.io Project. Permissions are organized by different 'scopes' which cover different aspects of the Form.io Project. Various Permission 'types' are assigned to those Scopes.
The Scope determines what level the Permission is being applied to while the Permission Type determines what actions or operations are allowed to be performed by the user within the given Scope.
Permission Scope
Form.io Permission are defined within certain "scopes" levels in a Project where the Permission is applied. These scopes are categorized as Project, Form, and Submission core entities:
Scope | Description | Entity | Property |
Project Scope | Project Level Access Defines the user permission to view forms and resources within a Project or view and update the Project's settings. | project | access |
Form Scope | Form Definition Access Defines the user permission to view, edit, or delete the form definition (JSON) within the API and application context. | form | access |
Submission Scope | Submission Data Permission Defines the user permission to view, edit, or delete the underlying submission data of a Form within the API and application context. | form | submissionAccess |
Permission Types
Within the Permission Scope are 8 different Permissions Types which grant users different functions and behaviors. As a general rule of thumb, the _all permissions are typically granted to Administrative roles, while the _own permissions are configured for end users to secure their access to the data they own.
Create Own
Create All
Read Own
Read All
Update Own
Update All
Delete Own
Delete All
Things to consider...
The owner of a project has full control to do any action within their Project.
By default Forms allow all roles to Read their definitions by default.
Submission access is disabled for every form by default. E.g. to enable anonymous submissions, you need to configure the Anonymous role to have create_own or create_all access in your specific form.
The update_all permission also grants the create_all permission for the Submission Data within the same form.
The read_all Project permission is currently used for determining index access for Forms and Roles.
Only the Project owner can delete a Project, regardless of the Delete permission other users may have.
Project Level Access Permissions
The Project-Level Permission scope determines the access rights and functionality users have within a given Project. These permissions govern actions such as reading a Project's JSON, updating Project settings, and other project-related functionality.
Project Level Permission Definitions:
Permission | Description |
Create All | The Create All permission will allow a user with one of the given Roles to create a form, resource, and role within the Project, designating them as the entity Owner. |
Read All | The Read All permission will allow a user with one of the given Roles to read all forms, resources, and roles within a Project, as well as the entire Project JSON itself regardless of the entity owner. |
Update All | The Update All permission will allow a user with one of the given Roles to update all forms, resources, and roles as well as the project itself regardless of the entity owner. |
Delete All | The Delete All permission will allow a user with one of the given Roles to delete Forms and Resources as well as various Project settings. |
The Project Settings carry special "property" that can ONLY be viewed and updated by either the Project owner, a User with Administrative permissions, or someone on a Team who has Project Admin access. This property is separated from other user roles since it can contain sensitive information. Project settings are also stored as an encrypted value to offer further security protection around this information.
How Are Project Permissions Configured?
Click the Access tab in the left-hand navigation bar within the Project. Roles are added to the Project-Level Access permissions for granular control of the given Project. In turn, users with the given role will have the Permission Type set for the Project Scope.
In the example below, the Authenticated Role has been added to the Read All and Update All Project-level permission type. This grants Authenticated Users permission to read and update the project JSON, however, they do not have permission to create or delete things like roles or forms within the Project. Meanwhile, users with the Administrator role can perform all CRUD (Create, Read, Update, Delete) functions within the Project context.
Project JSON
The following Project JSON shows the Project Scope permissions from the example screenshot above. Authenticated Role ID: 65fcac1e8e79f243350abd45 Administrator Role ID: 65fcac1e8e79f243350abd41
Project-Level Access Workflow Example
In most cases, Project-Level Permissions are utilized by users who are interacting with the Project programmatically using API tools like Postman. Users can perform various CRUD tasks using the Project's API, like updating the Project settings, retrieving a list of forms within the Project, and more. Read through the Form.io API documentation for more information.
In the following example, a GET request is made against the Project using a JWT token containing the Authenticated role, returning all Forms and Resources information within the Project. Because the Read All Project permission is configured with the Authenticated role, our user has access to this information.
Form Definition Access Permissions
The Form-Definition Access Permission, or Form Scope level, determines the access rights and functionality users have within a given Form. These permissions govern actions such as reading, updating, or deleting a Form's definition (Form JSON).
The Form-Definition Access Definition:
Permission | Description |
Read Own Form Definition | The Read Own permission will allow a user, with one of the given Roles, to read a form the user has created. |
Read Form Definition | The Read permission will allow a user, with one of the given Roles, to read the form. |
Update Own Form Definition | The Update Own permission will allow a user, with one of the given Roles, to update a form. A user can only update a form if they are defined as its owner. |
Update Form Definition | The Update permission will allow a user, with one of the given Roles, to read and edit the form. |
Delete Own Form Definition | The Delete Own permission will allow a user, with one of the given Roles, to delete a form. A user can only delete a form if they are defined as its owner. |
Delete Form Definition | The Delete permission will allow a user, with one of the given Roles, to delete the form. |
How Are Project Permissions Configured?
Click the Access tab within a Form or Resources. Roles are added to the Form Definition Access permissions for granular control of the given Form/Resource. In turn, users with the given role will have the Permission Type set within the Form Scope.
The Read Form definition permission must be configured with a corresponding Role to ensure that users assigned to that role can view the form embedded within an application
In the example below, the Authenticated Role has been added to the Read Form Definition Access. This grants Authenticated Users permission to Read the form (or view) within the context of an application. Meanwhile, users with the Administrator role can Read, Update, and Delete the form.
Form JSON
The following Form JSON shows the Form Scope permissions from the example screenshot above. Line 9 sets the Permission Scope while lines 11-40 set the permission types for the scope. Authenticated Role ID: 65fcac1e8e79f243350abd45 Administrator Role ID: 65fcac1e8e79f243350abd41
Submission Data Permissions
The Submission Data Permission, or Submission Scope level, determines the access rights and functionality users have for the underlying submisison-data within a given Form. These permissions govern actions such as creating, reading, updating, or deleting the submission data of a form.
Submission Data Permission Definition:
Permission | Description |
Create Own Submissions | The Create Own Submissions permission will allow a user with one of the Roles to create a Submission. Upon creating the Submission, the user will be defined as its owner. |
Create All Submissions | The Create All Submissions permission will allow a user with one of the Roles to create a new Submission and assign ownership of that Submission to another user. |
Read Own Submissions | The Read Own Submissions permission will allow a user with one of the Roles to read a Submission. A user can only read a Submission if they are defined as its owner. |
Read All Submissions | The Read All Submissions permission will allow a user with one of the Roles to read all Submissions regardless of who owns them. |
Update Own Submissions | The Update Own Submissions permission will allow a user with one of the Roles to update a Submission. A user can only update a Submission if they are defined as its owner. |
Update All Submissions | The Update All Submissions permission will allow a user with one of the Roles to update a Submission, regardless of who owns the Submission. Additionally with this permission, a user can change the owner of a Submission. |
Delete Own Submissions | The Delete Own Submissions permission will allow a user with one of the Roles, to delete a Submission. A user can only delete a Submission if they are defined as its owner. |
Delete All Submissions | The Delete All Submissions permission will allow a user with one of the Roles to delete a Submission, regardless of who owns the Submission. |
How Are Project Permissions Configured?
Click the Access tab within a Form or Resources. Roles are added to the Submission Data Permissions for granular control of the underlying submission data within a given Form/Resource. In turn, users with the given role will have the Permission Type set within the Form Scope.
The Create Own submission permission must be configured with a corresponding Role to ensure that users assigned to that role can submit the form embedded within an application
In the example below, the Authenticated Role has been added to the Create Own and Read Own Submission Data Permission. This grants Authenticated Users permission to submit the form (create their own submission) and read their data submission within the context of an application. Meanwhile, users with the Administrator role can create a submission and read ALL submissions made against the form.
Submission JSON
The following Submission JSON shows the Submission Scope permissions from the example screenshot above (not all permissions are displayed in the screenshot). Line 9 sets the Permission Scope while lines 11-53 set the permission types for the scope. Authenticated Role ID: 65fcac1e8e79f243350abd45 Administrator Role ID: 65fcac1e8e79f243350abd41
Other Permission Methods
Self Access Permissions
Self Access allows Submissions of this Resource to access themselves, as the owner of the submission. This works by assigning the _id of every submission within this resource to the "owner" property of that submission.
Field Match-Based Access
Field Match Access allows the user to configure submission access based on specific field values saved within the submission.
Field-Based Resource Access
Field-Based Resource Access assigns user permission(s) to a specific data submission based on a Resource referenced within the Form.
Group Permissions
Group Permissions build upon Field-Based Resource access and grant users permission based on a submission against a Group Resource. Groups are saved within a Resource and assigned to different users creating a one-to-many relationship between a group and its users. Form permissions can then leverage these groups to establish permissions for the users based on the group they are associated with.
Last updated
