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.
Project User Roles
Roles are a way of granting a group of users 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.
Every project contains its own distinct roles, 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.
Some common examples of roles could be as follows.
Manager - User with this role can manage other users (have admin access to the User resource)
Associate - A user who has access to read all submission data, but cannot create new records or manage other users.
Anonymous - A special role granted to users who are not authenticated.
Authenticated - A special role granted to users who are authenticated.
Admin - A user who has access to everything within a single project.
The whole purpose of Roles is to assign users access to certain Permissions which will be covered in a later section.
Default Roles
When a new Project is created, three (3) Roles are created by default:
Administrator
Authenticated
Anonymous
The Anonymous Role is a special Role that defines access within an Application for a User that is not authenticated. For example, a user that visits your application that has not yet registered or is not logged in. The Anonymous Role can be renamed, but not removed.
Creating and Configuring Roles
To create and configure a Role, navigate to the Access tab located within a Project anchored navigation bar on the left. You can Select the +New Role button to add a new Role, delete a Role by selecting the Trash Icon, or edit a Role name and description by selecting the Edit button.
Additional Roles can be defined and added to a project at any time. In the next section, we will discuss Permissions associated with Roles to define access to the submissions within your application.
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.
Permissions
There are eight (8) Permissions for each core entity within the Form.io platform. The core entities are Projects, Forms, and Submissions. The following eight permissions available for each, and are assignable on a per Role basis; Additionally, all Roles and Permissions and are self contained within each Project:
Create All
Read All
Update All
Delete All
Create Own
Read Own
Update Own
Delete Own
These Permissions grant users certain functions and behaviors that can be applied to a role within a Project and corresponding Application. As a general rule of thumb, the _all permissions are usually granted to Administrative roles, where as the _own permissions are usually configured for end users to secure each users data.
Facts to consider with the following definitions:
The owner of a project has full control to do any action within their Project.
Forms are configured to allow all roles to access 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 permissions for submissions, also grants the create_all permission for submissions 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.
Each of these basic Permissions are defined below:
Project Permissions
The Project Permissions define how access is granted to the forms and configurations of a project. It should be noted, that if project permissions are granted to a form, that does not mean that access to the submission data of that form is also granted (they are not hierarchical). This allows you to control who has access to data and forms independent from one another. The project permissions can be seen by navigating to the Access tab within the project page.
The following permissions are defined as follows.
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 and define the Owner of the entity. |
Read All | The Read All permission will allow a user with one of the given Roles to read all forms, resources and roles as well as the project itself regardless of who owns the entity. |
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 who owns the entity. |
Delete All | The Delete All permission will allow a user with one of the given Roles to delete all forms, resources and roles as well as the project itself regardless of who owns the entity. |
Project Settings
The project settings within a project are a special "property" on the project that can ONLY be viewed and updated by either the Project owner, a Project Admin, or someone on a Team who has Project Admin access. This property is separated because it can contain some sensitive credentials that you may not want to expose to other members of your team.
Project settings are also stored as an encrypted value to offer further security protection around this information.
Form and Submission Permissions
Within the Access section of every form, you can configure permissions allow access control on who can perform certain functions on a form as well as access to the submissions within that form. These permissions are based on CRUDI operations (Create, Read, Update, Delete, and Index), and are able to be associated to both Forms as well as Submissions. In addition, each permission is configured based whether a user is trying to perform those actions on their OWN records or other peoples records (ALL). In aggregate, this provides a total of 20 different permissions that can be configured on a per-form basis. They can be configured by clicking on the Access tab on each Form or Resource page.
These permissions are defined as follows.
Submission Data Permissions
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. |
Form Definition Access
Permission | Description |
Read Own Form Definition | The Read Own permission will allow a user, with one of the given Roles, to read a form. A user can only read a form if they are defined as its owner. |
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. |
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
