# Two-Factor Authentication

{% hint style="warning" %}
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.
{% endhint %}

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** :

{% file src="<https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F9Fm4wfvjNwol3OHcNGiY%2Fformio-2fa-template2.json?alt=media&token=68ba08e1-3557-4cb0-927d-f7c105a8c72e>" %}

2. Navigate to the **Portal Base Project.**
3. Click the **Staging** tab.
4. Click the **Import Template** tab and then the **Choose File** button.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F5b0pvWBuQbekcDPfqOgY%2F2fa.jpg?alt=media\&token=44f1181d-1c37-4894-8a33-9f6079a2f26a)

&#x20;  3\. Click on the **Choose File** button and select a downloaded file from Step 1.

&#x20;  4\. Click on the **Import Template to Live**. Note the following new Forms added to the project:

5. Select the **2fa JSON** file downloaded from step 1.&#x20;
6. Click the **Import Project Template** button.\
   This should add the following Form and Resource updates to the Project:

<table><thead><tr><th width="338.3333333333333">Name of forms</th></tr></thead><tbody><tr><td><strong>Two-Factor Authentication Form</strong> - will be used to authenticate users with a one-time 6-digit code from an auth app.</td></tr><tr><td><strong>Two-Factor Recovery Form</strong> - will be used to authenticate users with a one-time recovery code.</td></tr><tr><td><strong>Two-Factor Authentication Settings Form</strong> - a form for switch on/off 2FA settings for users.</td></tr></tbody></table>

7. Verify that the default User resource is updated with Two-Factor settings.
8. 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.&#x20;

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:**

<table><thead><tr><th width="310">Permission</th><th>Role(s)</th></tr></thead><tbody><tr><td>Create Own Submissions</td><td>Authenticated, Anonymous</td></tr><tr><td>Create All Submissions</td><td>Administrator</td></tr><tr><td>Read Own Submissions</td><td>Authenticated, Anonymous</td></tr><tr><td>Read All Submissions</td><td>Administrator</td></tr><tr><td>Update Own Submissions</td><td>Authenticated, Anonymous</td></tr><tr><td>Update All Submissions</td><td>Administrator</td></tr><tr><td>Delete Own Submissions</td><td>Authenticated</td></tr><tr><td>Delete All Submissions</td><td>Administrator</td></tr></tbody></table>

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F790aDlYIgiCp8tMkvSJo%2F3-1.png?alt=media\&token=1940ea44-9a0d-4a9f-bd61-709f970ba745)

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

<table><thead><tr><th width="236">Permission</th><th>Role(s)</th></tr></thead><tbody><tr><td>Read Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Read Form Definition</td><td>Administrator, Authenticated, Anonymous</td></tr><tr><td>Update Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Update Form Definition</td><td>Administrator</td></tr><tr><td>Delete Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Delete Form Definition</td><td>Administrator</td></tr></tbody></table>

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FrIEhjfCfeEt6BeBzJvG4%2F3-2.png?alt=media\&token=e02469ad-66c1-4d91-b5d2-3a7bf053b9ee)

4. Navigate to the **Two-Factor Recovery Form** and click the **Access** settings.
5. Apply the same permissions detailed above for the Two-Factor Authentication Form.
6. Navigate to the **Two-Factor Authentication Settings** form and click the **Access** setting.
7. Ensure there are no Roles assigned to any of the **Submission Data Permissions.**

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FQFot19rdKLx27sRkbsKV%2F5-1.png?alt=media\&token=376afa11-466d-4a16-a5f7-f0f861421842)

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

   <table><thead><tr><th width="236">Permission</th><th>Role(s)</th></tr></thead><tbody><tr><td>Read Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Read Form Definition</td><td>Administrator, Authenticated</td></tr><tr><td>Update Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Update Form Definition</td><td>Administrator</td></tr><tr><td>Delete Form Definition <br>(Restricted to owner)</td><td>N/A</td></tr><tr><td>Delete Form Definition</td><td>Administrator</td></tr></tbody></table>

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Ffd7ZqQ5gwD0vjwk0LK7G%2F5-2.png?alt=media\&token=e7dbe73c-c33d-4b3d-89e5-ea3d9c3fb636)

## 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.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FbWkD7DAcZfeqa1WW4dHu%2F2faenable.jpg?alt=media\&token=50f558ea-ee22-4d8a-b62e-6a9a1f023d88)

4. Scan a QR code with an Authenticator app (e.g. Google Authenticator, Microsoft Authenticator, Authy, etc.)
5. Enter the **6-digit code** and click the **Confirm** button.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F8kKkH7y4WuzagTD9qB7k%2F7.png?alt=media\&token=f4ecab4b-27ee-4c2c-9769-09d82ce1f2d8)

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.

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

{% hint style="info" %}
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
{% endhint %}

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

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FglPdfBbc7ehQLS6ZxCnV%2Frecoverycodes.jpg?alt=media\&token=77b006ee-ae12-4274-802b-b41e59dcf1b0)

## 2FA User Login

1. Navigate to the Form.io Deployed Portal
2. Login using Form.io authentication credentials&#x20;
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.&#x20;

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FhCRZHY5Qxr1PTNFss9nE%2F9.png?alt=media\&token=18b73b0c-5176-412f-b1e0-7c46f50c5d2f)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.form.io/developers/auth/two-factor-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.