Roles and Permissions

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.

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:

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.

{
  "_id": "661ffe3b2adabc01222babcd",
  "form": "6347275deaed4f145892abcd",
  "owner": "5bf5a5aa46322444b9f1abcd",
  "roles": [
    "6347275deaed4fe4ab926673"
  ],
  "access": [],
    "login": {
      "attempts": 0,
      "last": 1713372778481
    }
  },
  "data": {
    "email": "[email protected]"
  },
  "_fvid": 1,
  "project": "6347275deaed4fff5592asbcd",
  "state": "submitted",
  "externalIds": [],
  "created": "2024-04-17T16:52:11.998Z",
  "modified": "2024-04-17T16:52:11.998Z",
  "isAdmin": false,
  "onlyPrimaryWriteAccess": false
}

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:

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:

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

{
    "_id": "65fcac1d8e79fabc123",
    "title": "HR Application",
    "name": "ipajzfemjjsisnv",
    "type": "project",
    "owner": "6f6964636d65abc123",
    "plan": "commercial",
    "stageTitle": "Live",
    "access": [
        {
            "type": "create_all",
            "roles": [
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "read_all",
            "roles": [
                "65fcac1e8e79f243350abd45",
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "update_all",
            "roles": [
                "65fcac1e8e79f243350abd45",
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "delete_all",
            "roles": [
                "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:

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.

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

{
    "_id": "6622dea76a1d0363cd2b35f1",
    "title": "Job Application",
    "name": "jobApplication",
    "path": "jobapplication",
    "type": "form",
    "display": "form",
    "tags": [],
    "access": [
        {
            "type": "read_own",
            "roles": []
        },
        {
            "type": "read_all",
            "roles": [
                "65fcac1e8e79f243350abd45",
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "update_own",
            "roles": []
        },
        {
            "type": "update_all",
            "roles": [
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "delete_own",
            "roles": []
        },
        {
            "type": "delete_all",
            "roles": [
                "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:

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.

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

{
    "_id": "6622dea76a1d0363cd2b35f1",
    "title": "Job Application",
    "name": "jobApplication",
    "path": "jobapplication",
    "type": "form",
    "display": "form",
    "tags": [],
    "submissionAccess": [
        {
            "type": "create_own",
            "roles": [
                "65fcac1e8e79f243350abd45"
            ]
        },
        {
            "type": "create_all",
            "roles": [
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "read_own",
            "roles": [
                "65fcac1e8e79f243350abd45"
            ]
        },
        {
            "type": "read_all",
            "roles": [
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "update_own",
            "roles": []
        },
        {
            "type": "update_all",
            "roles": [
                "65fcac1e8e79f243350abd41"
            ]
        },
        {
            "type": "delete_own",
            "roles": []
        },
        {
            "type": "delete_all",
            "roles": [
                "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.