Roles and Permissions
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 their 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 with 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:
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.
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.
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 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. |
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.
These permissions are defined as follows.
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. |
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 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.
Field Based Resource Access is useful if you want to assign a permission to specific submission data based on assignment in a field.
For example, let's imagine you are building a Clinic application, and wish to assign patients to physicians within the clinic. One of your requirements may also be to only allow physicians within that clinic to view the data of patients in which they have been assigned. Field based resource access permissions is perfect for this example.
To accomplish this example, you would first need to add a Select component on the patient resource, and then configure that select component to use the data type of Resource and then select the physician resource. Once this field exists within the patient resource, you can then add that physician as having "Read" access within the field based resource access section. Once this is done, any physician that is assigned to a patient will only be able to view the patient records that they are assigned. The following permissions can be defined for any resource field within the form.
Permission | Description |
Read | The Read permission will allow a resource, defined in the submission, to read all of the submission data. |
Create | The Create permission will allow a resource, defined in the submission, to read and create all of the submission data. |
Write | The Write permission will allow a resource, defined in the submission, to read, create and edit all of the submission data except for the Submission Resource Access and Owner information. |
Admin | The Admin permission will allow a resource, defined in the submission, to read, create, edit and delete all of the submission data. |
This section is also used to accomplish Group Permissions, which is discussed below.
Field Match Access is useful if you want to assign an access to some submissions based not only on the user's role, but also on the value of the specified submissions's or form's field.
For example, you have a 'privacy' field on the form which can be "public" or "private" and you want to give access to read all the "public" submissions for authenticated users.
For each permission that can be granted the following criteria can be used to perform the "match" for access.
Roles - A selection of roles that can be applied to that match
Field Path - The path for the field to determine if the value conditionally applies this permission.
Operator - The operator to use for comparison of the field value and the value criteria.
Type - The data type of the value.
Value - The value to use in the comparison to determine if this is a match and the permission should apply.
To use Field Match Access, specify a form's or a submission's field's path (e.g. "data.privacy" for the "privacy" field within the form, "state" for the "state" field of the submission) and also a value which it should be compared with. You can select one of the available operators for comparison and specify a type of the value. If you add multiple conditions for a single role, the access will be given if at least one of them passed.
Values of arrays should be separated by "," without spaces. Strings should NOT be wrapped in the brackets.
The permissions that can be granted are as follows.
Permission | Description |
Read | If the field value matches the criteria, then the user of the specified role will be able to read the submission. |
Create | If the field value matches the criteria, then the user of the specified role will be able to create a submission. |
Write | If the field value matches the criteria, then the user of the specified role will be able to update and read the submission. |
Admin | If the field value matches the criteria, then the user of the specified role will be able to create, read, and update the submission. |
In addition to providing access based on Roles within a project, you can also grant access to certain users who belong to a certain "group". A Group can be defined as a separate Resource that is then assigned to users, thereby placing those users into different contexts. In order to establish a permission system based on these groups, we must first setup our project to enable Group structure. We will start by creating a Group resource.
In order to take advantage of the group permission system, you must first create a "group" resource. A group can really be defined as any entity that is used to coalesce different sets of users into different groups. Here are some good examples of what would be defined as a Group.
Department - Used to place employees in their own departments.
Team - Could be used to place athletes into their teams.
Class - Could be used for education to collect teachers and students together into a "class" group.
For this generic example, however, we will just call our group "Group" which can be done by creating a new resource, and we will just add a single textfield called "Name".
Once this group is created, we can now create a few example groups by simply using this resource and submitting a few records. We will just create two new groups called, "Teachers" and "Students"
We can now create our "join" resource to bring users and groups together.
To create a many-to-many relationship between Users and Groups (where users can be associated with many groups, and vice-versa) we will create another Resource that will serve the sole purpose of "joining" these two resources together. This is typically called a Join Resource and is very powerful in establishing a many-to-many relationship between two resources.
A one-to-many relationship is also possible by simply adding the "Group" resource as a field that belongs on the User resource, but for this example, we will cover the more common use case of using a join resource.
To create this Join Resource, we will do the following.
Create a new Resource and call it UserGroup
Drag and drop a Select component
Give the component a label of User
Click on Data tab, and then select Resource under Data Source Type.
Next, select User as the resource.
Scroll down and then type the following for Item Template.
<span>{{ item.data.email }}</span>Press Save to save the field on the form.
Repeat steps 2 - 7, but this time do it for the Group resource. Make the Item Template as
<span>{{ item.data.name }}</span>
Now save this resource.
Next, you will click on the Actions tab for this resource, and add a new Action called Group Assignment and then click on Add Action button. Under the action settings, for Group Resource, select Group and for the User Resource, select User.
Next click Save Action to add this action to the form.
We can now create a few submissions in this resource (by clicking the Use tab) so that we can associate some users with some groups. Here is an example of the submission data after we have done this.
The next thing we need to do is to add a Group to a form (as a field), and then provide access to that form based on the group that the user belongs to. For example, we could create an Evaluation form, and then add the following Group as a field to that form.
Now that you have the field added to your form, we can now edit the Access tab and configure the following under the Field Based Resource Access section.
This configuration basically says the following.
Any students who create evaluations can read other students evaluations, but not teachers evaluations. Any teachers who create evaluations can read other teachers evaluations, but not student evaluations.
This is how you can enable groups of users to have different access than other groups of users based on their associations with other resources within a Form.io project.
Group permissions works by assigning the Group ID (submission id) as a "role" that is added to the users submission object. This can be seen by viewing the users submission JSON and viewing the "roles" property which will contain any group id's that the user has been assigned.
In addition to allowing Groups to be established, it is also possible to establish roles, where further categorization of users can be made within a single group. For example, if you wish to have a Group defined as a Classroom, the Group Roles system allows you to assign users to a Classroom, but then choose if they are a Teacher or a Student within that classroom, and then grant separate permissions based on their role within the Group.
This is configured exactly as you would configure the Group Permissions above, but with just a few differences.
When you create your Join Resource, you will need to create a field that will be used to establish the "Roles" within that group. This can simply be a Select dropdown with the Values of that select dropdown show the roles you wish to provide.
When you configure the Group Assignment action, you will now want to select this new field as the Role.
Finally, when you assign the permissions of the Group to the form, you will want to assign which role within the form can have which permission.
