Roles and Permissions

Roles and Permissions are a very important and differentiating aspect of the <form.io> platform. They provide developers many capabilities that are required for enterprise applications that are not found in other form or API platforms.

Roles

A Role is a group of users that have a shared set of defined permissions with respect to submission data within an Application.

Some common example names of Roles used in enterprise applications include Administrator, Sales Agent, Registered User, Authenticated User, Anonymous User, and many, many more.

  • A Project may have an unlimited number of Roles defined within it.
  • Users within a Role share the same permissions.
  • Users within a Role inherit the permissions associated with that Role.
  • A User may be assigned to more than one Role.

<form.io> allows developers the ability to easily define Roles to control how a group of users access submissions within their Project. A site owner can manage the user access to such tasks as creating, updating or deleting submissions by assigning a user to a specific Role. These Roles have full access to the forms within the project, but are easily edited if needed in the future. This process will be discussed with more detail in the Permissions section of this User Guide.

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 Settings tab located within a Project at the top right corner of the page and then click the Roles button on the left side. Select the +New Role button to add a new Role, delete a Role by selecting the Trash Icon, and edit a Role name and description by selecting the Edit button.

When naming Roles, they are organized alphabetically and capital letters will be listed before lowercase letters. Staying consistent when naming your Roles will keep the Role list organized.

3 roles

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:

Submission Permissions

(Defined within each Form)

  • Create All Submission

    • The Create All Permission will allow a user, with the given role, to create a Submission. The user creating the submission may assign ownership at creation time. (Default: None)
  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view any Submission made within the Form, regardless of who owns that Submission. (Default: None)
  • Update All Submission

    • The Update All Permission will allow a user, with the given role, to update any Submission made within the Form, regardless of who owns the Submission. Additionally this Permission allows the user to change the owner of any Submission. (Default: None)
  • Delete All Submission

    • The Delete All Permission will allow a user, with the given role, to delete any Submission made within the Form, regardless of who owns the Submission. (Default: None)
  • Create Own Submission

    • The Create Own Permission will allow a user, with the given role, to create a Submission. The user will be assigned as the owner of the submission. (Default: None)
  • Read Own Submission

    • The Read Own Permission will allow a user, with the given role, to read any Submission made within the form, where they are defined as the owner. (Default: None)
  • Update Own Submission

    • The Update Own Permission will allow a user, with the given role, to update any Submission made within the form, where they are defined as the owner. (Default: None)
  • Delete Own Submission

    • The Delete Own Permission will allow a user, with the given role, to delete any Submission made within the form, where they are defined as the owner. (Default: None)

Form Permissions

(Defined within each Form)

  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view the Form, regardless of who owns it. (Default: All Roles)
  • Update All Submission

    • The Update All Permission will allow a user, with the given role, to update the Form, regardless of who owns it. (Default: None)
  • Delete All Submission

    • The Delete All Permission will allow a user, with the given role, to delete the Form, regardless of who owns it. (Default: None)
  • Read Own Submission

    • The Read Own Permission will allow a user, with the given role, to read the Form, if they are defined as the owner. (Default: None)
  • Update Own Submission

    • The Update Own Permission will allow a user, with the given role, to update the Form, if they are defined as the owner. (Default: None)
  • Delete Own Submission

    • The Delete Own Permission will allow a user, with the given role, to delete the Form, if they are defined as the owner. (Default: None)

Project Permissions

(Defined within each Project)

  • Create All Permission

    • The Create All Permission will allow a user, with the given role, to create a new Project entity (Form or Role). The user creating the entity may assign ownership at creation time. (Default: Administrator)
  • Read All Permission

    • The Read All Permission will allow a user, with the given role, to view the Project definition. Note: Only Administrative users can view the Project Settings data. (Default: Administrator)
  • Update All Permission

    • The Update All Permission will allow a user, with the given role, to update the Project definition. Note: Only Administrative users can edit the Project Settings data. (Default: Administrator)
  • Delete All Permission

    • The Delete All Permission will allow a user, with the given role, to delete a Project entity (Form or Role), regardless of who owns it. (Default: Administrator)

Configuring Roles and Permissions

Once Roles have been created, there are a few different ways to configure and manage Roles/Permissions within your Project.

  1. Select Edit next to any role on your role Settings page:

    4 edit role

    This will give you a list of all forms or resources that hold the selected Role, along with their Permissions, within the entire project. Simply hit edit next to the form you want to configure and apply your changes:

    5 edit permission

    Now you can select the Roles you want to associate with each Permission.Remember to save any changes made:

    6 permission

  2. Assign permissions by clicking the Permissions button located at the top right of the page within a form or resource. Each permission may be assigned a role or more than one role, by clicking in the Roles field. After assigning roles to your Permissions, click the Save button at the bottom. Remember, you can always add, delete, and edit a role at anytime.

The Project owner will have all permissions to any Form and Resource submissions by default.

Role Assignment

Once Roles and Permissions have been configured, you can implement your configurations to a Resource or Form by adding an Authentication Action or a Role Assignment Action. To add an Action, click the Action tab on the top right of the page within a Form or Resource. Click the Select an Action button for a list of available Actions.

More information about the Authentication Action and Role Assignment Action can be found in the Actions Section.

Self Access Permissions

The Self Access Permission checkbox provides a way for “submissions” to access their own records regardless of their role or other permissions assigned to the form. This is useful when you have User submissions created on behalf of the user, and then at a later time, they are onboarded in the system and need to have access to their own record. In this specific case, they are logged in as that submission, but are not the “owner” of the submission (since they didn’t create their record). This checkbox allows them to have access to their record since the _id of the record is the same as the _id they provide in the Authenticaiton token as the User ID.

Submission Resource Permissions

Submission Resource Permissions allow specific Resources (e.g. users), to access specific Submissions. A Resource with Resource Permissions may access a Submission without having Roles and Permissions configured for the Form, which the submission is a child of. Submission Resource Permissions are useful in a scenerio where access is needed, but for few members, which makes a new role less applicable.

There are three permission types for Submission Resource Permissions:

  • Read: The Resource(s) defined with access, may read all the contents of the given submission.
  • Write: The Resource(s) defined with access, may read all the contents of the given submission, and edit any information, with the exception of the Submission Resource Permissions and the owner property.
  • Admin: The Resource(s) defined with access, may read and edit all of the contents of the given submission.

Permission Assignment


Submission Resource Permissions can be configured on any Form with a resource select component. In the Form permission editor, Submission Resource Access will be available for configuration. For each permission, you will see a unique list of each resource select component within the current Form. Selecting any resource for one of the permissions, will grant any selected resources on a new submission, that specific access to the submission.

In the following example, the users resource select component is being assigned to the Read permission. On any following form submission, all of the selected users resources will be granted read access to that individual submission, regardless of the forms existing roles and permissions. The Submission Resource Permissions settings are configured on a per form basis, but the individual access is contained within each form submission.