# 1. Student Login

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

---

## 1. Student Login

### 1.1 Email and Password Login
**What it does:** The primary way a Student signs in to the platform. The Student enters their registered email address and password on the login screen; the system verifies both against the stored credentials, applies all applicable access controls (account status, lockout state, IP allow/deny lists, location policy, 2FA requirement), and on success establishes an authenticated session that grants access to the Student's learning panel. The login screen is the single entry point for the web platform and the mobile app, and it adapts its visible fields and follow-up steps based on the account's configuration (e.g., showing a second-factor step when 2FA is enabled).

**Sub-features:**
- Login screen with email and password fields, input validation (format check, trimming, case handling for email), and clear inline error messages
- "Show/hide password" toggle and auto-fill support for password managers
- "Forgot password" link on the login screen routing to the reset flow
- "Remember me" checkbox for trusted devices
- Rate limiting on login attempts per account and per IP to slow brute-force attacks
- Progressive failure feedback: generic "invalid email or password" message (never reveals which field was wrong)
- Pre-authentication checks applied in order: account status (active/suspended/deactivated), lockout state, IP allow/deny lists, location policy
- Post-verification checks: 2FA challenge if enabled or mandatory
- Session establishment on success: session record created, login event logged, Student redirected to the Student Dashboard
- Login attempt logging: every attempt (success and failure) recorded with timestamp, IP, device, and failure reason
- Mobile app parity: identical credential verification with device-bound session tokens
- Audit logging of the student login

**Student User Journey:**
1. Student opens the platform URL in a browser (or launches the mobile app) and lands on the login screen, which shows the email field, password field, "Remember me" checkbox, "Forgot password?" link, and the "Sign in" button.
2. Student types their registered email address; the field validates the format as they type and shows an inline error if the format is invalid.
3. Student types their password, using the show/hide toggle to confirm no typos, and ticks "Remember me" because this is their trusted device.
4. Student clicks "Sign in". The button shows a brief loading state while the system verifies the credentials and runs the pre-authentication checks (account status, lockout, IP and location policy).
5. Because 2FA is enabled for the account, the screen transitions to the second-factor step: "Enter the 6-digit code sent to your registered phone" with a 60-second resend countdown.
6. Student enters the OTP from their phone. The system validates it; on success the session is established, the login event is written to the log, and the screen transitions to the Student Dashboard.
7. The dashboard shows a personalized greeting, quick stats (subjects unlocked, trial days remaining, hours studied, lessons completed), and the standard navigation (courses, assessments, progress, profile menu).
8. If at any point the password was wrong, Student would see the generic error "Invalid email or password" with the attempt count remaining before a temporary lock, and the failed attempt would appear in the login activity log.
9. Student opens the profile menu → "Login activity" and confirms the successful login is recorded with timestamp, device, and location.

**Rules & Edge Cases:**
- The error message never distinguishes between "email not found" and "wrong password" to prevent account enumeration.
- Email addresses are matched case-insensitively; passwords are case-sensitive.
- A suspended or deactivated account cannot log in at all; the message differs by state (suspended = temporary with appeal path; deactivated = permanent closure notice).
- If the account is locked from repeated failures, the login screen shows the remaining lockout time and the support contact instead of accepting credentials.
- If the source IP is on a deny list, the attempt is rejected before credential verification and logged as an IP-block event.
- If 2FA is mandatory and the Student has not enrolled, login pauses at a guided enrollment step rather than failing.
- Every login attempt — success, failure, block — is written to the login activity log with full context.
- Sessions created via this method are subject to all session policies (timeouts, concurrency, remember-me).
- The student login is audit-logged with the account, the outcome, and the timestamp.

### 1.2 OTP-Based Login Verification (Password + OTP)
**What it does:** A login mode in which the password is the first factor and a one-time password (OTP) delivered to a registered channel (SMS or email) is the second factor, required to complete the login. The OTP is generated at the moment the password is verified, delivered to the Student's registered channel, and must be entered within its validity window to complete the login. This can be applied as a platform-wide or account-scoped login policy without requiring the Student to manage an authenticator app.

**Sub-features:**
- OTP delivery channel selection: SMS to registered phone and/or email, with fallback channel if the primary fails
- OTP generation: 6-digit numeric code, cryptographically random, single-use
- OTP validity window (e.g., 5 minutes) with countdown shown on the entry screen
- OTP entry screen with auto-advance digit fields and paste support
- Resend with cooldown (e.g., 60 seconds) and a maximum resend count per login attempt
- Attempt limit: a fixed number of wrong OTP entries (e.g., 5) invalidates the current OTP and requires a fresh one
- Login completion: on valid OTP, session established and Student redirected to the Student Dashboard
- Failure handling: expired OTP, wrong OTP, and delivery failure each produce distinct, actionable messages
- Delivery failure fallback: if SMS fails, offer email delivery or a support-assisted path
- Full logging of each OTP issuance, verification, failure, and expiry
- Audit logging of the OTP-based login verification

**Student User Journey:**
1. Student returns to the login screen and enters email and password, then clicks "Sign in". The password verifies successfully.
2. The screen transitions to the OTP step: "We sent a 6-digit code to +27-XXXXX-XXXXX. It expires in 04:59." A "Resend code" link is greyed out with a 60-second countdown.
3. Student receives the SMS, types the 6 digits into the auto-advancing fields (or pastes the code), and clicks "Verify".
4. The system validates the OTP. On success, the session is established and Student is redirected to the Student Dashboard; the login is logged as "password + OTP — success".
5. To test the failure path, Student logs out and repeats the login, entering a wrong OTP. The screen shows "Incorrect code. 4 attempts remaining." After five wrong entries, the message changes to "This code is no longer valid. Request a new code."
6. Student clicks "Resend code" after the cooldown, receives a fresh OTP, and completes the login.
7. Student opens the profile menu → "Login activity" and confirms both the successful and failed OTP events are recorded with timestamps, IP, and device.

**Rules & Edge Cases:**
- The OTP is single-use: a verified code cannot be reused, even within its validity window.
- The OTP expires at the end of its validity window; an expired code produces an "expired" message with a resend option, not a generic error.
- Wrong-OTP attempts are counted per issued code; exceeding the limit invalidates that code and requires a new issuance.
- Resends are rate-limited (cooldown plus a maximum per login session) to prevent SMS abuse.
- If the registered phone is unreachable (no network, number changed), the Student can switch to email delivery if registered, or use the support-assisted recovery path.
- OTPs are never logged in full; only the event (issued/verified/failed/expired) and channel are recorded.
- OTP delivery latency is out of the platform's control; the UI always shows the expiry countdown so the Student knows when to resend.
- The OTP-based login verification is audit-logged with the account, the channel, and the timestamp.

### 1.3 Social Login (Google, Facebook)
**What it does:** Allows a Student to authenticate using an external identity provider (Google or Facebook) instead of a platform password. On first use, the social identity is linked to a platform account (created or matched), and on subsequent logins the social provider's verified identity is accepted as proof of identity. The Student can add or remove a social provider from their profile, subject to the platform's linking and consent rules.

**Sub-features:**
- First-login account creation: social profile (name, email, profile picture) used to create the platform account, with required fields (e.g., phone, grade) prompted afterwards
- Account matching: if the social provider's email matches an existing platform account, offer to link rather than create a duplicate
- Account linking: a Student with an existing email/password account can add a social provider from profile settings (with password verification)
- Unlinking: remove a social provider from the account, blocked if it would leave the account with no authentication method
- Consent capture: the social provider's data usage is covered by the platform privacy policy at first login
- Session behavior identical to password login (2FA policy, session policies, logging all apply)
- Provider outage handling: if the provider is unreachable, the Student falls back to email/password login with a notice
- Social login usage and failure visibility per provider
- Audit logging of the social login

**Student User Journey:**
1. Student opens the login screen and sees "Continue with Google" and "Continue with Facebook" buttons alongside the email/password form.
2. Student clicks "Continue with Google". The Google consent screen appears; Student authorizes the platform to access their name, email, and profile picture.
3. Because this is the Student's first social login, the platform creates a new account from the social profile and prompts for the remaining required fields (phone, grade, education board).
4. Student completes the onboarding fields and is redirected to the Student Dashboard with an active session.
5. Later, Student opens Profile → "Connected accounts" and adds Facebook by verifying their existing password first, then authorizing Facebook.
6. Student opens Profile → "Connected accounts" and removes Facebook; the system confirms the account still has Google and email/password, so the removal is allowed.
7. Student opens the profile menu → "Login activity" and confirms the social logins are recorded with provider, outcome, and timestamp.

**Rules & Edge Cases:**
- A social login can never be the only authentication method; the account must retain at least one working method (password or another provider).
- Linking a social provider to an account requires verifying the account's existing password first (prevents an attacker from linking their own social identity to a victim account).
- Unlinking is blocked if the account has no other working authentication method.
- If the provider's email is already used by another platform account, the system offers linking/merge review rather than silently creating a duplicate.
- Social provider outages degrade gracefully: the button is hidden or shows an unavailable notice; email/password login remains available.
- All social logins are logged with provider, outcome, and account, and are subject to the same lockout and IP policies as password logins.
- Data received from the provider (name, email, picture) is stored per the privacy policy and is visible in the Student's profile data export.
- The social login is audit-logged with the provider, the account, and the timestamp.

### 1.4 Two-Factor Authentication
**What it does:** Adds a second factor to the Student's login so that possession of the password alone is insufficient. The Student enrolls a second factor (an authenticator app or SMS), and on each login the system presents the second-factor challenge after the password is verified. The Student can view, change, or remove their enrolled factor from profile settings, subject to the platform's security policy.

**Sub-features:**
- Enrollment: choose a second factor (authenticator app via QR code, or SMS to registered phone)
- Authenticator app setup: QR code scan, confirmation code entry to verify the app
- SMS setup: send a test code to the registered phone and verify it
- Backup codes: generate a set of single-use backup codes for when the primary factor is unavailable
- Login challenge: after password verification, present the second-factor entry screen
- Change factor: switch from one factor type to another (requires verifying the current factor first)
- Remove factor: disable 2FA (requires password + current factor verification), subject to policy
- Recovery: use a backup code or the support-assisted path when the primary factor is lost
- Status visibility: the Student can see whether 2FA is on and which factor type is enrolled
- Audit logging of the two-factor authentication

**Student User Journey:**
1. Student opens Profile → "Security" → "Two-Factor Authentication" and sees that 2FA is currently off, with an "Enable" button.
2. Student clicks "Enable" and chooses "Authenticator app". The screen shows a QR code and a manual entry key.
3. Student scans the QR code with their authenticator app, enters the 6-digit code the app shows, and clicks "Verify". The system confirms the app is enrolled.
4. The screen generates a set of backup codes; Student copies them to a safe place and clicks "I have saved my backup codes".
5. On the next login, after entering the password, Student is prompted for the 6-digit code from the authenticator app and completes the login.
6. Later, Student opens Profile → "Security" and sees 2FA is on with "Authenticator app" as the enrolled factor, plus a "Regenerate backup codes" option.
7. Student opens the profile menu → "Security activity" and confirms the enrollment and each 2FA challenge are recorded with timestamps.

**Rules & Edge Cases:**
- Enrolling or changing a factor requires verifying the current factor (or password for the first enrollment).
- Removing 2FA requires both the password and the current factor, and is subject to the platform's security policy (some accounts may have mandatory 2FA that cannot be removed).
- Backup codes are single-use; each code can be used once, and the remaining count is shown.
- If the primary factor is lost and no backup codes remain, the Student must use the support-assisted recovery path.
- The second-factor challenge is presented only after the password is verified; a wrong password never triggers an OTP.
- 2FA challenges are rate-limited and logged (issued/verified/failed/expired) without storing the code itself.
- The two-factor authentication enrollment, change, and removal are audit-logged with the account, the factor type, and the timestamp.