Two-Factor Authentication

The following Two-Factor Authentication workflow is only compatible with Form.io Resource-based authentication. It's very common to utilize other authentication methods like OIDC or SAML for the deployed developer portal or custom applications. Please refer to the authentication provider's documentation to set up 2FA with these alternative methods.

The Form.io 2FA (Two-Factor Authentication) is a security feature within Form.io that adds an extra layer of protection to user accounts by requiring two modes of verification before granting access. In Form.io’s API-driven platform, 2FA can be configured for the Form.io Deployed Developer Portal by integrating authentication forms and workflows detailed below.

Integrating 2FA into an existing project:

In most recent Form.io platform deployments, 2FA is already integrated by default for the Portal Base project, managing authentication for the Form.io Deployed Developer Portal. Confirm this by checking that the Portal Base Project includes the necessary Two-Factor Authentication and Recovery forms, as well as fields to support the 2FA workflow within the User Resource.

If your Portal Base Project does not include 2FA, follow the instructions below:

Importing 2FA Forms/Resource

Implementation into an existing project:

1. Download the following project template JSON :

34KB

formio-2fa-template2.json

1. Navigate to the Portal Base Project.

2. Click the Staging tab.

3. Click the Import Template tab and then the Choose File button.

3. Click on the Choose File button and select a downloaded file from Step 1.

4. Click on the Import Template to Live. Note the following new Forms added to the project:

1. Select the 2fa JSON file downloaded from step 1.

2. Click the Import Project Template button. This should add the following Form and Resource updates to the Project:

Name of forms
Two-Factor Authentication Form - will be used to authenticate users with a one-time 6-digit code from an auth app.
Two-Factor Recovery Form - will be used to authenticate users with a one-time recovery code.
Two-Factor Authentication Settings Form - a form for switch on/off 2FA settings for users.

1. Verify that the default User resource is updated with Two-Factor settings.

2. Go to the Two-Factor Authentication Form access settings and set permissions as required. Example settings are provided below:

Setting Up Permissions

With the Forms and Resources in place, Permissions will be delegated to ensure the correct users can enable and use 2FA.

1. Navigate to the Two-Factor Authentication Form and click the Access tab.

2. Ensure the following Permissions have been set for the Submission Data Permission:

Permission	Role(s)
Create Own Submissions	Authenticated, Anonymous
Create All Submissions	Administrator
Read Own Submissions	Authenticated, Anonymous
Read All Submissions	Administrator
Update Own Submissions	Authenticated, Anonymous
Update All Submissions	Administrator
Delete Own Submissions	Authenticated
Delete All Submissions	Administrator

1. Ensure the following Permissions have been set for the Form Definition Access:

Permission	Role(s)
Read Form Definition (Restricted to owner)	N/A
Read Form Definition	Administrator, Authenticated, Anonymous
Update Form Definition (Restricted to owner)	N/A
Update Form Definition	Administrator
Delete Form Definition (Restricted to owner)	N/A
Delete Form Definition	Administrator

1. Navigate to the Two-Factor Recovery Form and click the Access settings.

2. Apply the same permissions detailed above for the Two-Factor Authentication Form.

3. Navigate to the Two-Factor Authentication Settings form and click the Access setting.

4. Ensure there are no Roles assigned to any of the Submission Data Permissions.

1. Ensure the following Permissions have been set for the Form Definition Access:

   Permission	Role(s)
   Read Form Definition (Restricted to owner)	N/A
   Read Form Definition	Administrator, Authenticated
   Update Form Definition (Restricted to owner)	N/A
   Update Form Definition	Administrator
   Delete Form Definition (Restricted to owner)	N/A
   Delete Form Definition	Administrator

Enabling Two-Factor Authentication:

1. Login as a developer portal User or Admin.

2. Navigate to Account Settings and click the Two-Factor Authentication tab.

3. Click Turn on 2FA button to enable.

1. Scan a QR code with an Authenticator app (e.g. Google Authenticator, Microsoft Authenticator, Authy, etc.)

2. Enter the 6-digit code and click the Confirm button.

10. Please, write down 10 recovery codes in a safe place to be able to log in to your account if you lose access to your auth app or lose your device. Each code is acceptable for one-time login. After login, it will be deleted.

1. Keep a record of the recovery codes and store in a safe place .

These codes can be used if the user loses access to their authenticator app or if the device is lost. Each code is valid for a single login and will be deleted after use

1. Click the Turn Off 2FA within Account Settings to disable 2FA.

2FA User Login

1. Navigate to the Form.io Deployed Portal

2. Login using Form.io authentication credentials

3. Enter the 2FA code from the authenticate application (or a recovery code) After submitting, the user should be redirected to the Form.io portal page.