# Crazy Two-Factor Authentication (2FA) - Setup Guide
Follow the steps below to integrate the **Crazy Two-Factor Authentication (2FA)** plugin into your Bubble application.

---

## 1. Install the Plugin

1. Navigate to your Bubble application's **Plugins** tab.
2. Search for **Crazy Two-Factor Authentication**.
3. Install the plugin.

---

## 2. Update Your User Data Type

Create the following fields in your **User** data type:

| Field Name              | Data Type | Description                                                                                              |
| ----------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
| **secret_key**          | Text      | Stores the user's unique TOTP secret key.                                                                |
| **hashed_backup_codes** | Text      | Stores the hashed backup codes generated during 2FA setup.                                               |
| **is_2fa_enabled**      | Yes/No    | Indicates whether Two-Factor Authentication is enabled for the user.                                     |
| **is_2fa_verified**     | Yes/No    | Indicates whether the user has successfully completed 2FA verification during the current login session. |

---

## 3. Enable Two-Factor Authentication

When the user enables 2FA:

1. Run the **Enable 2FA** plugin action.
2. The plugin returns:

  * QR Code
  * Secret Key
  * Backup Codes
  * Hashed Backup Codes
3. Display the QR Code to the user.
4. Display the Backup Codes **only once** and advise the user to print or save them in a secure location.
5. Save the following values in your database:

  * **secret_key**
  * **hashed_backup_codes**
6. Set **is_2fa_enabled** to **Yes**.

> **Important:** Backup codes are displayed only once. They cannot be recovered later. If lost, users must generate a new set of backup codes.

---

## 4. Verify the Authenticator Code

After the user logs in:

1. Check whether **is_2fa_enabled** is **Yes**.
2. If enabled, prompt the user to enter the 6-digit code from their authenticator application.
3. Run the **Verify 2FA** plugin action.
4. If verification succeeds:

  * Set **is_2fa_verified** to **Yes**.
  * Allow the user to continue.
5. If verification fails:

  * Display the returned error message.
  * Prompt the user to try again.

---

## 5. Verify Using a Backup Code

If the user no longer has access to their authenticator application:

1. Allow the user to select **Use Backup Code**.
2. Prompt the user to enter one of their backup codes.
3. Run the **Verify Backup Code** plugin action.
4. Provide:

  * **secret_key**
  * **hashed_backup_codes**
  * **backup_code**
5. If the backup code is valid:

  * Save the returned **hashed_backup_codes** back to the database.
  * Set **is_2fa_verified** to **Yes**.
  * Allow the user to continue.
6. If the backup code is invalid:

  * Display the returned error message.

> **Note:** Each backup code can only be used once. After a successful verification, the plugin automatically marks the used backup code as invalid and returns an updated **hashed_backup_codes** value. Be sure to save the updated value to your database.

---

## 6. Regenerate Backup Codes (Recommended)

If the user has lost their backup codes or has used most of them:

1. Run the **Enable 2FA** action again (or your future **Regenerate Backup Codes** action).
2. Save the new **hashed_backup_codes**.
3. Display the newly generated backup codes to the user.
4. Discard all previously generated backup codes.

---

## Recommended Login Flow

1. User logs in with their username/email and password.
2. If **is_2fa_enabled** is **No**, continue to the application.
3. If **is_2fa_enabled** is **Yes**, prompt the user to:

  * Enter an Authenticator Code, or
  * Use a Backup Code.
4. After successful verification, set **is_2fa_verified** to **Yes** and continue to the application.

---

## Security Best Practices

* Never store backup codes in plain text.
* Store only the returned **hashed_backup_codes**.
* Display backup codes only once during setup.
* Encourage users to print or securely store their backup codes.
* Regenerate backup codes immediately if they are lost or compromised.

---

## Support

For additional information, examples, and updates, please visit the Bubble Forum:

https://forum.bubble.io/t/new-plugin-release-crazy-two-factor-authentication/312054