# 1. User Login

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

---

## 1. User Login

### 1.1 Email and Password Login
**What it does:** The primary authentication method for all user types. A user 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 user's 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 (see 4.2)
- "Remember me" checkbox (see 5.2)
- 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 for the role
- Session establishment on success: session record created, login event logged, user redirected to their default landing screen (role-specific)
- Role-aware landing: each user type lands on their own panel home (Super Admin Dashboard, Student Dashboard, etc.)
- 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

**Super Administrator User Journey:**
1. Super Admin 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. Super Admin types their registered email address; the field validates the format as they type and shows an inline error if the format is invalid.
3. Super Admin types their password, using the show/hide toggle to confirm no typos, and ticks "Remember me" because this is their trusted workstation.
4. Super Admin 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 Super Administrator role, 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. Super Admin enters the OTP from their phone. The system validates it; on success the session is established, the login event is written to the security log, and the screen transitions to the Super Admin Dashboard.
7. The dashboard shows the Super Admin's name, role badge, and the standard navigation (modules, notifications, profile menu). A notification bell shows any pending items (e.g., unapproved content, open support tickets).
8. If at any point the password was wrong, Super Admin would see the generic error "Invalid email or password" with the attempt count remaining before a temporary lock (e.g., "3 more attempts before a temporary lock"), and the failed attempt would appear in the login activity log.
9. If the account were suspended, the screen would instead show "Your account is suspended. Please contact support" with the support contact details, and no further attempts are accepted until re-activation.

**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 the account's role has mandatory 2FA and the user has not enrolled, login pauses at a guided enrollment step (see 3.1) rather than failing.
- Every login attempt — success, failure, block — is written to the login activity log with full context (see 8.1).
- Sessions created via this method are subject to all session policies (timeouts, concurrency, remember-me) in section 5.

### 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. This is distinct from 2FA enrollment (section 3) in that it can be applied as a platform-wide or role-scoped login policy without requiring users to manage an authenticator app. The OTP is generated at the moment the password is verified, delivered to the user's registered channel, and must be entered within its validity window to complete the login.

**Sub-features:**
- Policy configuration: enable password+OTP login globally or per role (e.g., all admin roles, all staff)
- 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 user redirected to their panel
- 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

**Super Administrator User Journey:**
1. Super Admin opens System Settings → Security Policy → Login Methods and confirms that "Password + OTP" is enabled for the Super Administrator role (and reviews which other roles have it enabled).
2. Super Admin logs out and returns to the login screen to test the configured behavior.
3. Enters email and password and clicks "Sign in". The password verifies successfully.
4. The screen transitions to the OTP step: "We sent a 6-digit code to +91-XXXXX-XXXXX. It expires in 04:59." A "Resend code" link is greyed out with a 60-second countdown.
5. Super Admin receives the SMS, types the 6 digits into the auto-advancing fields (or pastes the code), and clicks "Verify".
6. The system validates the OTP. On success, the session is established and Super Admin is redirected to the Super Admin Dashboard; the login is logged as "password + OTP — success".
7. To test the failure path, Super Admin 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."
8. Super Admin clicks "Resend code" after the cooldown, receives a fresh OTP, and completes the login.
9. Super Admin opens Security Monitoring → 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 user 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.
- This login mode and 2FA (section 3) can both be active; the policy defines which challenge is presented (typically the 2FA enrollment state takes precedence once enrolled).
- OTP delivery latency is out of the platform's control; the UI always shows the expiry countdown so the user knows when to resend.

### 1.3 Social Login (Google, Facebook)
**What it does:** Allows users 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 Super Admin controls which providers are enabled, for which user types, and how social logins are governed (linking rules, consent, session behavior).

**Sub-features:**
- Provider enable/disable per provider (Google, Facebook) and per user type (e.g., students and parents may use social login; admin roles may be excluded)
- First-login account creation: social profile (name, email, profile picture) used to create the platform account, with required fields (e.g., phone) 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 user with an existing email/password account can add a social provider from profile settings (with password verification)
- Unlinking: remove a social provider from an 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, users fall back to email/password login with a notice
- Admin monitoring: social login usage statistics and failure rates per provider

**Super Administrator User Journey:**
1. Super Admin opens System Settings → Security Policy → Login Methods → Social Login.
2. Reviews the current state: Google enabled for students and parents, Facebook disabled, admin roles excluded from social login.
3. Enables Facebook for students and parents, and confirms the exclusion list for privileged roles (Super Admin, Billing Administrator, etc.).
4. Saves; the change applies immediately — the login screen now shows both "Continue with Google" and "Continue with Facebook" buttons for eligible user types.
5. Super Admin opens Security Monitoring → Login Activity, filters by method "Social", and reviews the first-day usage: successful logins, new accounts created, and failures per provider.
6. A user reports they logged in with Google but a second, duplicate-looking account appeared. Super Admin opens the user directory, searches by the user's email, finds the two accounts, and reviews their login history.
7. Super Admin confirms the social email matched an existing account that the user had not linked. Using the account-merge support process, Super Admin merges the duplicate into the primary account, preserving the older account's data, and the merge is audit-logged.
8. Super Admin reviews the provider health view: if Facebook's API is degraded, the login screen automatically hides the Facebook button and shows "Facebook login is temporarily unavailable — use email and password."

**Rules & Edge Cases:**
- A social login can never be the only authentication method for a privileged role; admin roles must always have email/password (and typically 2FA).
- 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 (password disabled and no other provider linked).
- 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 user's profile data export.

### 1.4 Single Sign-On (SSO) for Enterprise and Institute Integrations
**What it does:** Enables organizations (training institutes, corporate partners, enterprise clients) to authenticate their users through the organization's own identity provider, so users log in once with their organizational credentials and gain access to the platform without a separate platform password. The Super Admin configures each SSO integration, maps organizational identities to platform roles, and governs the lifecycle of SSO-provisioned accounts.

**Sub-features:**
- SSO integration setup: configure an identity provider connection per organization (standard SSO protocols), with test-connection validation
- Organization scoping: each SSO integration is bound to one organization (institute/enterprise) and only its users
- Role mapping: organizational groups/attributes map to platform roles (e.g., institute staff → Teacher role, admin contact → Institute Administrator)
- Just-in-time provisioning: first SSO login creates the platform account automatically using mapped attributes, subject to the organization's enrollment policy
- De-provisioning: when the organization removes a user (or the SSO assertion stops being issued), the platform account is suspended per policy
- Session behavior: SSO sessions follow the same session policies; logout can be local or federated (end the organizational session too)
- Fallback policy: if the identity provider is unreachable, the organization's users are blocked from SSO login with a clear notice (platform password fallback only if the organization opted in)
- Admin monitoring: SSO login activity, provisioning events, and provider health per integration
- Audit logging of all SSO configuration changes and provisioning events

**Super Administrator User Journey:**
1. A training institute requests SSO so its 40 staff and 500 students can log in with the institute's existing accounts. Super Admin opens System Settings → Integrations → SSO and selects "New SSO integration".
2. Super Admin enters the organization name, the identity provider's connection details, and runs the test-connection check, which validates the configuration and shows a success/failure result.
3. Super Admin configures the role mapping: the institute's "staff" group maps to the Teacher role, the "admin" contact maps to Institute Administrator, and "students" map to the Student role.
4. Super Admin sets the provisioning policy: just-in-time creation enabled for students and staff, with required fields (phone) prompted on first login; de-provisioning set to "suspend on removal".
5. Saves and activates the integration. The institute's users now see "Continue with [Institute]" on the login screen when they select the institute's portal entry.
6. The institute's first user logs in via SSO; the platform creates the account, assigns the mapped role, and the user lands on their panel. Super Admin sees the provisioning event in the SSO activity view.
7. Weeks later, the institute removes a departing staff member from its directory. The next SSO login attempt by that user fails, and per policy the platform account is suspended. Super Admin sees the de-provisioning event in the activity view and confirms the suspension in the user directory.
8. The identity provider has an outage. Super Admin sees the provider-health alert in the SSO monitoring view, and the institute's users see "Single sign-on is temporarily unavailable. Please try again later." on the login screen.
9. Super Admin reviews the SSO audit log to confirm all configuration changes and provisioning events are recorded, and exports the log for the institute's quarterly review.

**Rules & Edge Cases:**
- SSO is organization-scoped: an identity from one organization's provider can never authenticate into another organization's users or into platform staff roles.
- Platform staff (Super Admin and internal roles) never authenticate via an organization's SSO; SSO covers the organization's own users only.
- Role mapping is explicit; an unmapped organizational group results in a denied or default-restricted account flagged for admin review, never a silent grant of access.
- De-provisioning suspends (not deletes) accounts so data is retained and the action is reversible if the removal was a mistake.
- If the provider is unreachable, SSO logins fail closed (blocked) unless the organization explicitly opted into a platform-password fallback for its users.
- All SSO configuration changes, provisioning, and de-provisioning events are audit-logged with actor and timestamp.
- SSO sessions are subject to the same session policies (timeouts, concurrency) as any other session.