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 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.
When a new Project is created, three (3) Roles are created by default:
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.
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.
Adding a new role to a project
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.
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:
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 Project Access section of a project
The following permissions are defined as follows.
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.
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.
Configuring Access on a per-form or per-resource
These permissions are defined as follows.
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.
Group Self Access works by first assuming this resource is a "group" in which an authenticated user is assigned. This provides a way for members of that group to have certain access to the group submission itself. The following configurations apply.
- None - Group Self Access is not utilized
- Admin - Group members can view, edit, or delete this resource submission.
- Write - Group members can view and edit this resource submission.
- Read - Group members can read this resource submission.