# Two Factor Authentication

## **Overview** 

DBSync's Org-Level Two-Factor Authentication (2FA) enhances security by requiring a one-time password (OTP) via email during login. Org admins can enable or disable this feature for their organization.

### **Enabling/Disabling 2FA**

**Who Can Enable/Disable:** Only **Org Admins**.

**Enable 2FA (Org Admin)**

1. Navigate to **AppCenter › Organization › Settings › Security**.
2. Toggle **Enable Two‑Factor Authentication (Email OTP)** **ON**.
3. **Confirmation modal** appears:
   * Impact summary: **All users in this org will be required to verify with an email OTP on every login.**
   * Select the checkbox: **I understand the impact** (must be checked).
   * Click **Enable 2FA**.
4. **System actions (automatic):**
   * Persist org‑level flag `2fa_enabled = true`.
   * Create **audit log** entry (who, when, from where, change detail).
   * Send **org‑wide email**: *2FA Enabled* (see template in §3).
5. **Success toast**: **2FA enabled for your organization.**
6. Optional: An **info banner** appears on the Dashboard for all users until their first 2FA login.

**Disable 2FA (Org Admin)**

1. Navigate to **AppCenter › Organization › Settings › Security**.
2. Toggle **Enable Two‑Factor Authentication (Email OTP)** **OFF**.
3. **Confirmation modal** appears:
   * Warning that security is reduced and OTP will no longer be required.
   * Checkbox **I acknowledge**.
   * Click **Disable 2FA**.
4. **System actions (automatic):**
   * Persist org‑level flag `2fa_enabled = false`.
   * Create **audit log** entry.
   * Send **org‑wide email**: *2FA Disabled* (see template in §3).
5. **Success toast**: **2FA disabled for your organization.**

### **Login and Authentication Flow**

**Pre‑condition:** Org has 2FA **enabled** and the user account is **not** currently locked.

1. **Sign‑in**: User enters **Username** and **Password** on the DBSync login page and clicks **Sign in**.
2. **2FA challenge screen** loads:
   * Shows masked registered email (e.g., **j•••@example.com**).
   * **OTP is sent automatically** to the registered email.
   * A **countdown timer** indicates validity (**5 minutes**).
   * **Resend code** is disabled until the timer reaches the resend threshold (e.g., 30–60 seconds), after which the user can request a new OTP.
3. **Enter OTP**: User enters the **6‑digit OTP** in a single field (auto‑advance supported) and clicks **Verify**.
4. **Successful verification**:
   * User is signed in.
   * System records `last_2fa_at` timestamp (for future periodicity features).
   * Session is established.
5. **Incorrect OTP**:
   * 1st–2nd failed attempts: Inline error “Incorrect code. Try again.”
   * **3rd consecutive failure**: Account is **temporarily blocked for 1 hour**.\
     • UI shows lockout message with next retry time.\
     • **Emails** are sent to the **User**, the **Org Admin**, and **DBSync AppCenter.**
6. **Expired OTP**:
   * UI shows “Code expired.”
   * User can click **Resend code** to receive a fresh OTP and retry.
7. **Email delivery failure**:
   * UI shows a non‑blocking alert: “We couldn’t send the code. Please check your email address or try again.”
   * User can click **Resend code**; admins can verify the user’s registered email if failures persist.
8. **Lockout recovery**:
   * Account auto‑unlocks after **1 hour**.
   * Org Admin (or DBSync Support) can **manually unblock** via the **AppCenter Org object** flag.

**Frequency**: 2FA is required **on every login**. “Trust this device” is **not available** in this release.

### **Email Templates**

**OTP Email:**

* **Subject:** Your DBSync Login Verification Code
* Includes OTP, expiry time, support info, and security disclaimer.

**Delivery Requirements:**

* Use a reliable email service provider.
* Add headers to avoid spam/junk.
* Include login URL for user convenience.

### **Error Handling**

**Scenarios & Actions:**

* **Expired OTP:** Prompt to regenerate.
* **3 Failed Attempts:** Account blocked for **1 hour**.
* **Failed Email Delivery:** Option to resend OTP.

**Blocked Account Notifications:**

* **User Notification:**
  * Informs about 1-hour block, retry instructions, and support contact.
* **Org Admin Notification:**
  * Identifies blocked user, email ID, and timestamp.
  * Advises internal verification and contact with DBSync Support.
* **DBSync AppCenter Notification:**
  * Email with org name, ID, admin email, and timestamp.

**Unblocking Mechanism:**

* Admins can unblock via a new flag in the AppCenter Org object.

### **Security Measures**

* OTPs are unique, secure, and time-bound.
* Accounts lock after repeated OTP failures.
* OTP logs maintained for audit.

### **User Roles and Permissions**

| Role      | Can Enable/Disable 2FA | Must Use 2FA (if enabled) |
| --------- | ---------------------- | ------------------------- |
| Org Admin | Yes                    | Yes                       |
| User      | No                     | Yes                       |