# 3. Two-Factor Authentication

User Type: **Super Administrator**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 3. Two-Factor Authentication

### 3.1 2FA Setup and Management
**What it does:** Provides the enrollment and ongoing management of two-factor authentication for user accounts. A user enrolls by registering a second-factor channel (an authenticator app with a TOTP secret, or SMS/email OTP delivery), completing a confirmation step that proves they control the channel, and from then on presenting that second factor at login. The Super Admin governs 2FA at the policy level: which roles must have it, which may opt in, and the platform-wide adoption posture.

**Sub-features:**
- Enrollment flow: choose channel (authenticator app or SMS/email), register the channel, confirm with a test code
- Authenticator app support: QR code and manual secret entry for TOTP apps, with time-sync guidance
- SMS/email OTP channel: bound to the user's verified phone/email
- Backup codes: a set of single-use recovery codes generated at enrollment, shown once, downloadable
- Enrollment completion: 2FA marked active only after a successful confirmation code
- Management screen: view enrolled channels, add a second channel, replace a lost channel (with identity + current 2FA verification), revoke channels
- Policy configuration: mandatory 2FA per role (e.g., all admin and staff roles), optional for others
- Guided enrollment at login: users of a mandatory-2FA role who have not enrolled are walked through enrollment at their next login before they can proceed
- Admin enforcement actions: force-enable for a user, reset a user's enrollment (see 3.3)
- Adoption reporting: platform-wide and per-role 2FA enrollment status
- Full audit logging of enrollment, channel changes, and policy changes

**Super Administrator User Journey:**
1. Super Admin opens System Settings → Security Policy → Two-Factor Authentication.
2. Reviews the current policy: mandatory for Super Admin, Billing Administrator, and all staff roles; optional for students and parents.
3. Confirms the mandatory list is correct for the current staffing model, and saves (no change needed).
4. Opens the 2FA adoption report: per-role enrollment percentages, the list of mandatory-role users not yet enrolled, and recent enrollment activity.
5. Sees two new staff members (hired last week) who have not enrolled. Super Admin opens the pending list, confirms both have logged in at least once (triggering the guided enrollment prompt), and sends them a reminder notice with a link to the enrollment screen.
6. Both staff members complete enrollment; the adoption report updates to 100% for mandatory roles.
7. Super Admin reviews the enrollment audit log: each enrollment shows the user, channel type, timestamp, and confirmation success, confirming the process is being followed correctly.
8. Super Admin schedules a monthly review of the adoption report so any new hire who skips enrollment is caught within the week.

**Rules & Edge Cases:**
- Enrollment is not complete until the user successfully verifies a test code from the newly registered channel.
- A user cannot have 2FA "half-enrolled": if confirmation fails, the channel is discarded and enrollment must be redone.
- Backup codes are displayed exactly once at enrollment; the system stores only their hashed form and cannot re-display them.
- If the second-factor channel is lost (phone changed, app wiped), the user re-enrolls after identity re-verification (password + backup code or support-assisted verification).
- Mandatory-2FA policy blocks login completion for unenrolled users of that role, presenting the guided enrollment flow instead of a dead end.
- Changing or revoking a channel always requires passing the current 2FA challenge (or support-assisted verification) to prevent an attacker from swapping in their own channel.
- All enrollment, channel-change, and policy changes are audit-logged with actor and timestamp.

### 3.2 OTP-Based Second Factor
**What it does:** The runtime second factor: after the first factor (password) is verified, a one-time password is issued to the user's enrolled channel and must be entered correctly within its validity window to complete the login. This is the enforcement mechanism that makes 2FA effective at every login, and it applies uniformly whether the channel is an authenticator app (TOTP) or SMS/email delivery.

**Sub-features:**
- TOTP verification for authenticator-app users: 6-digit code valid for a 30-second window, with a small skew tolerance (±1 window) for clock drift
- SMS/email OTP for delivery-channel users: 6-digit code with a validity window (e.g., 5 minutes)
- Entry screen: auto-advance digit fields, paste support, clear expiry countdown
- Attempt limit: a fixed number of wrong entries (e.g., 5) invalidates the current challenge
- Resend (delivery channels only) with cooldown and a maximum per login
- Trusted-device option: on a recognized device, skip the second factor for a trust window (e.g., 30 days) if policy allows for the role
- Fallback: backup codes accepted when the primary channel is unavailable; each backup code is single-use
- Exhausted-recovery path: if all options fail, login is blocked and support-assisted recovery is required
- Full logging: every challenge issued, verified, failed, expired, or skipped (trusted device) is recorded

**Super Administrator User Journey:**
1. Super Admin opens the platform and enters their email and password on the login screen.
2. Because 2FA is enabled, the screen transitions to the second-factor step. Super Admin's enrolled channel is an authenticator app, so the prompt reads "Enter the 6-digit code from your authenticator app" with no resend option.
3. Super Admin opens the authenticator app, reads the current 6-digit code, and enters it. The system validates it against the TOTP window and, on success, redirects to the Super Admin Dashboard.
4. On a different occasion, Super Admin logs in from a new laptop. After password + TOTP, the screen offers "Trust this device for 30 days?" Super Admin accepts, and for the next 30 days logins from that laptop skip the second factor (the trust is recorded and visible in the session view).
5. Super Admin's phone is lost. At next login the authenticator code is unavailable, so Super Admin enters one of the backup codes generated at enrollment. The code is accepted, marked used, and the remaining-code count drops.
6. Super Admin immediately re-enrolls 2FA with a new authenticator app on their replacement phone (identity verified with password + a remaining backup code), and revokes the old channel.
7. To test the failure path on a test account, a wrong TOTP is entered five times; the challenge is invalidated and the login is blocked for that attempt with a "try again with a new code" message.
8. Super Admin opens Security Monitoring and reviews the 2FA event log: each challenge shows issued/verified/failed/expired/skipped status, channel, and timestamp, confirming the enforcement is working and the trusted-device skip is recorded.

**Rules & Edge Cases:**
- TOTP codes are single-use per time window; a code from the previous window is accepted only within the skew tolerance.
- Delivery-channel OTPs are single-use and expire at the end of the validity window; an expired code produces an "expired" message with resend.
- Five wrong entries invalidate the current challenge; a new login attempt issues a fresh challenge.
- Backup codes are single-use; when the remaining count is low (e.g., ≤2), the user is prompted to regenerate the set (which requires passing a 2FA challenge).
- Trusted-device skip is role-gated: privileged roles may be excluded from trusted-device skip by policy, requiring the second factor at every login.
- If all recovery options are exhausted (no channel, no backup codes), login is blocked and only support-assisted recovery (with identity verification by support) can restore access.
- Every 2FA challenge event is logged for auditing; the code values themselves are never logged.

### 3.3 Per-User 2FA Enable/Disable
**What it does:** Controls the 2FA state of individual accounts. Users can self-manage their own 2FA (enable, add channels, disable) subject to system policy, while the Super Admin can enforce 2FA state for any user under policy — force-enabling it for accounts that must have it, or resetting a user's enrollment when their second factor is lost and they cannot self-recover.

**Sub-features:**
- Self-service 2FA toggle in profile settings (Security section)
- Identity re-verification required to disable: current password plus a passing 2FA challenge
- Policy override: roles with mandatory 2FA cannot self-disable; the toggle is shown disabled with an explanation
- Admin action: force-enable 2FA for a user (the user completes enrollment at next login via the guided flow)
- Admin action: reset a user's 2FA enrollment (clears channels and backup codes) with support-assisted identity verification
- Admin action: view any user's 2FA status (enabled, channel types, last used) without seeing secrets
- Notification to the user when an admin changes their 2FA state
- Audit logging of all enable/disable/reset actions with actor, target, and reason

**Super Administrator User Journey:**
1. A staff member reports their phone was stolen and they no longer have access to their authenticator app or backup codes. They open a support request.
2. Super Admin opens the request and the user's record in the user directory, confirming the account identity through the support-assisted verification process (confirming registered details and an OTP to the registered phone).
3. Satisfied with the identity, Super Admin performs "Reset 2FA" on the user's record, entering the reason ("Device lost — support-assisted recovery").
4. The user's 2FA channels and backup codes are cleared. The user is notified: "Your two-factor authentication was reset by an administrator. You will be asked to set it up again at your next login."
5. At the user's next login, after the password, the guided enrollment flow presents automatically; the user enrolls a new authenticator app and completes confirmation.
6. Super Admin reviews the 2FA status view for the account: now "Enabled — authenticator app", and the audit trail shows the reset (actor, reason, timestamp) and the subsequent enrollment.
7. Separately, Super Admin reviews the mandatory-2FA pending list and finds a user of a mandatory role who has not enrolled. Super Admin performs "Force-enable 2FA" on that account; the user's next login is paused at the guided enrollment step until they complete it.
8. Super Admin exports the 2FA action audit log for the quarter to include in the security audit evidence package.

**Rules & Edge Cases:**
- Disabling 2FA always requires passing the current 2FA challenge in addition to the password — an attacker with only the password cannot remove the second factor.
- Users of mandatory-2FA roles see the disable toggle greyed out with the explanation "Two-factor authentication is required for your role"; they cannot self-disable.
- A 2FA reset clears all channels and backup codes; the user must re-enroll from scratch at next login.
- Admin 2FA actions (force-enable, reset) always require a recorded reason and are audit-logged with the acting admin.
- The user is always notified when an admin changes their 2FA state, so unauthorized changes are visible to the account owner.
- 2FA status is visible to admins (enabled/disabled, channel types, last-used time) but channel secrets and backup codes are never exposed in any admin view.