> For the complete documentation index, see [llms.txt](https://help.form.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.form.io/dev/authentication-and-authorization/resource-based-authentication/two-factor-authentication.md).

# Two Factor Authentication

Using 2FA with Formio Resource-based 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 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

### Integrating into an existing project:

1. **Download** the following project **template** **JSON** :

{% file src="/files/s9IVuWcc8RP6zeaWgTLC" %}

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

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2F5peyOkG94jBKHRhr5m3s%2F2fa.jpg?alt=media&amp;token=2dee8a89-9c72-40e2-a244-bf70c02203db" alt=""><figcaption></figcaption></figure>

1. Select the downloaded file from Step 1.
2. Click on the **Import Template to Live**. Note the following new Forms added to the project:

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

6. Verify that the default User resource is updated with Two-Factor settings.
7. Proceed to the next section to configure permissions for the newly incorporated forms.

### **Setting Up Permissions**

With the Forms and Resources in place, delegate permissions 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:**

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

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FiPT1Xg8kZit3KeHocR1m%2F3-1.png?alt=media&amp;token=76ae0d5f-bbde-4443-9170-2b9ec1d87704" alt=""><figcaption></figcaption></figure>

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>

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FRXQKAqZNcPVugjppyUwN%2F3-2.png?alt=media&amp;token=e67535f3-2cdd-4f67-b309-0f2256a2f534" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FyMyuVXJOzifuI8WuQpGC%2F5-1.png?alt=media&amp;token=2715e75e-ef09-42e7-b25d-52624b02dcf3" alt=""><figcaption></figcaption></figure>

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>

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FeNfxxmXrsUoLcUB03BFU%2F5-2.png?alt=media&amp;token=8eb29a59-7919-4d31-b193-3a1ed1ae81f7" alt=""><figcaption></figcaption></figure>

## Enabling Two-Factor Authentication:

1. Login to the Developer Portal as a **User** or **Admin.**
2. Navigate to **Account Settings** and click the **Two-Factor Authentication** tab.
3. Click **Turn on 2FA** button to enable.

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FO4PpWjRCv7E4lvNjARlw%2F2faenable.jpg?alt=media&amp;token=0deeb542-bd9b-4700-b732-d8eaee71dbba" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FuRX0ixyGlic8drmKm734%2F7.png?alt=media&amp;token=6ad45ec6-c771-4588-a252-5e247441e68f" alt=""><figcaption></figcaption></figure>

3. Keep an offline record of up to 10 recovery codes and store them in a safe place .

{% hint style="info" %}
These codes can be used if the user loses access to the authenticator app or if the device is lost. Each code is valid for a single login and will be deleted after use
{% endhint %}

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FvBw0BSf1oswLr414FVN1%2Frecoverycodes%20(1).jpg?alt=media&amp;token=5e76fe1a-8d88-4e1b-a884-6720dd0932dd" alt=""><figcaption></figcaption></figure>

## 2FA User Login

1. Navigate to the Form.io Developer Porta.
2. Login using Form.io authentication credentials.
3. Enter the 2FA code from the authentication application (or a recovery code).

After submitting, the user should be redirected to the Form.io portal page.

<figure><img src="https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2F5NHxgbTztWVPttJCmhDq%2F9.png?alt=media&amp;token=5d8531fb-a349-45a6-8f5d-56b787cff876" alt=""><figcaption></figcaption></figure>

## Disabling 2FA

Simply click the **Turn Off 2FA** within Account Settings to disable 2FA.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://help.form.io/dev/authentication-and-authorization/resource-based-authentication/two-factor-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.