# 7. Access Control & Permissions

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

---

## 7. Access Control & Permissions

### 7.1 Role-Based Access Control
**What it does:** Enforces that every user can access only the features, sections, and data permitted by their role. This is the core authorization mechanism across the platform: every request is checked against the user's role-to-permission mapping, at both the feature level (which sections a role may open) and the data level (which records a role may see). Anything not explicitly permitted is denied, and the enforcement is consistent across the web interface and all underlying service surfaces.

**Sub-features:**
- Role-to-permission mapping enforced on every request (web and service surfaces)
- Feature-level access: which sections/modules a role can open and which actions it can perform within them
- Data-level scoping: which records a role can see (e.g., a teacher sees only their assigned courses; a support agent sees only tickets in their queue)
- Deny-by-default: any feature, action, or record not explicitly permitted is denied
- Consistent denial experience: a clear "you don't have permission to view this" message with an optional "request access" path
- Access-denied logging: every denial recorded with user, role, target, and timestamp
- Prompt propagation: permission changes take effect on the user's next request, without requiring re-login
- Super Administrator exemption: the Super Admin role has full access and is not subject to scoping

**Super Administrator User Journey:**
1. A new staff member joins as a Content Reviewer. Super Admin assigns them the Content Reviewer role (via Role & Permission Management), which permits the review queue and read access to content, but nothing else.
2. The staff member logs in. Their navigation shows only the sections their role permits: the review queue and content views. There is no Pricing, no Billing, no user directory.
3. The staff member manually navigates to the Pricing Management URL. The request is denied server-side and they see "You don't have permission to access this section." with a "Request access" link.
4. The denial is logged: user, role (Content Reviewer), target (Pricing Management), timestamp.
5. A month later, the review process expands and Super Admin adds "approve resource library items" to the Content Reviewer role. The staff member's access updates on their next request — no re-login needed — and the new action appears in their review queue.
6. Super Admin reviews the access-denied log for the quarter to confirm enforcement is working as intended and to spot any role that is repeatedly hitting denials (a signal the role's permission set may be misconfigured).
7. For a teacher, Super Admin verifies data scoping: the teacher sees only their own courses and students in every view, while a different teacher with the same role sees a different record set.

**Rules & Edge Cases:**
- Permission changes take effect on the next request, not only at next login; a user mid-session gains/loses access promptly.
- Data scoping means two users with the same role can see different record sets (different teachers, different queues); scoping is per-user within the role.
- All access-denied events are logged with user, role, and target for audit and for spotting misconfiguration.
- The Super Administrator role has full access and is not subject to feature or data scoping.
- Denial is enforced at the service layer, not just the UI: a hidden menu item cannot be reached by direct navigation or by calling the underlying service without permission.
- A user with multiple roles gets the union of the permitted features, but data scoping still applies per the scoping rules.

### 7.2 Configure Permissions per Role
**What it does:** Lets the Super Administrator define exactly which features, actions, and data scopes each role can access, and adjust them over time as the organization changes. Permissions are drawn from a central catalog, assigned to roles through a role editor, and changes propagate immediately to every user holding the role, with a preview of the blast radius before saving.

**Sub-features:**
- Permission catalog: the full list of grantable permissions (features, actions within features, data scopes)
- Role editor: toggle permissions on/off per role, organized by module
- Preset role templates (Billing Administrator, Teacher, Content Reviewer, Support Agent) with sensible defaults
- Custom roles with arbitrary permission sets
- Change preview: before saving, see what a permission change will affect (how many users, which capabilities gained/lost)
- Separation-of-duties flags: warn on risky combinations (e.g., a role that can both create discount codes and approve refunds)
- Immediate propagation of permission changes to all holders of the role
- Audit logging of every permission change with before/after state and affected user count

**Super Administrator User Journey:**
1. The finance team asks to separate duties: the person who processes refunds should not also be able to change payment gateway configurations. Super Admin opens Role & Permission Management and selects the Billing Administrator role.
2. Opens the role editor and reviews the current permission set, organized by module. Billing currently includes both "Process refunds" and "Manage payment gateway configurations".
3. Creates a new custom role, "Refunds Processor", copying the Billing Administrator set but with "Manage payment gateway configurations" removed. Reviews the preset vs. custom difference.
4. The editor shows a separation-of-duties note confirming the new role no longer combines the two sensitive capabilities.
5. Super Admin assigns the Refunds Processor role to the staff member who handles refunds, and removes the full Billing Administrator role from them.
6. Reviews the change preview: "Affects 1 user — loses: manage payment gateway configurations; keeps: process refunds, view billing."
7. Saves; the change propagates immediately. The staff member's next request reflects the reduced access, and the gateway-config section is now denied for them (and logged if attempted).
8. Super Admin reviews the audit entry for the change: before/after permission sets, the acting admin, and the affected user count, and confirms the separation of duties is in place.

**Rules & Edge Cases:**
- Removing a permission a user is actively using ends that capability on their next action; in-progress screens may complete their current request but not initiate new ones with the lost permission.
- Critical separation-of-duties combinations are flagged in the editor as warnings (not hard blocks), so the Super Admin can make an informed, deliberate choice.
- Every permission change is audit-logged with before/after state, the acting admin, and the affected user count.
- Preset templates are starting points; editing a preset role edits that role for all its holders (the preview makes this explicit).
- A role with no users can still be edited and saved; it takes effect when users are assigned to it.
- The permission catalog is the single source of truth: a role cannot grant a permission that is not in the catalog.

### 7.3 Activate, Suspend, and Deactivate Accounts
**What it does:** Controls the lifecycle state of any user account. Active accounts can log in and use the platform; suspended accounts are temporarily blocked (data retained, reversible) typically pending review or due to a policy violation; deactivated accounts are permanently closed, triggering data handling per the privacy policy. The Super Admin can change any account's state, individually or in bulk, with a recorded reason and user notification.

**Sub-features:**
- Activate: enable a new or previously suspended account, restoring access
- Suspend: temporarily block access with a reason; data retained; reversible; active sessions ended
- Deactivate: permanently close the account; triggers data handling per the privacy policy (retention, anonymization, deletion per 9.3)
- Bulk status changes for groups of accounts (e.g., a cohort, an institute's departed staff)
- User notification on status change with the reason and the appeal/contact path
- Subscription handling on suspension/deactivation: pause, prorate, or cancel per policy
- Reason presets plus free-text note for every status change
- Audit logging of all status changes with actor, target, reason, and timestamp

**Super Administrator User Journey:**
1. A user is flagged for a policy violation (e.g., abusive behavior toward a teacher). Super Admin opens the user's record in the user directory and reviews the flagged activity and the violation details.
2. Selects "Suspend account", chooses the reason preset "Policy violation", and adds a note referencing the incident.
3. Confirms; the account is immediately blocked from logging in, and its active sessions are ended on their next request. The user is notified: "Your account has been suspended for [reason]. Contact support to appeal."
4. Per policy, the user's recurring billing is paused so they are not charged while blocked.
5. The user appeals through support. Super Admin (or the assigned admin) reviews the appeal with the evidence, and finds the violation is resolved/misunderstood.
6. Selects "Activate" to restore access; the user is notified their account is active again, and billing resumes per policy.
7. For a different account that should be closed permanently (user requested closure), Super Admin selects "Deactivate", reviews the data-handling summary (what will be deleted, what is retained for legal reasons and anonymized, the downstream effects such as cancelling the subscription and releasing an institute license seat), and confirms.
8. Super Admin reviews the status-change audit log: each change shows actor, target, reason, and timestamp, and the deactivation shows the data-handling outcome.

**Rules & Edge Cases:**
- Suspension is immediate: the account cannot log in, and active sessions are terminated on their next request.
- Suspension pauses recurring billing per policy to avoid charging a blocked user; resuming activation resumes billing per policy.
- Deactivation is irreversible from the UI; reactivation requires a new registration or a support-assisted restore within the retention window.
- Deactivation triggers the privacy data-handling flow (see 9.3): personal data deleted or anonymized per legal retention, with downstream effects (subscription cancellation, seat release) handled as part of the flow.
- Bulk status changes require a confirmed preview of the affected account count and a recorded reason; they are audit-logged as a single batch with the member list.
- All status changes notify the user with the reason and the appeal/contact path, and are audit-logged with actor, reason, and timestamp.

### 7.4 Account Lockout after Repeated Failed Login Attempts
**What it does:** Temporarily locks an account (or the login path for an email or IP) after a threshold of consecutive failed login attempts, preventing brute-force and credential-stuffing attacks. Lockouts are configurable in threshold, duration, and scope, can escalate progressively for repeat offenders, and are visible to the Super Admin for review and one-click unlock after verification.

**Sub-features:**
- Configurable failure threshold (e.g., 5 consecutive failed attempts)
- Configurable lockout duration (e.g., 15 minutes) or progressive lockout (longer after repeated lockouts, capped)
- Scope: per account, per IP, or both (independent counters)
- Lockout notice shown to the user with the remaining time and the support contact
- Admin view of locked accounts with filters (by account, IP, time) and one-click unlock after identity verification
- Alert in security monitoring when lockouts spike (possible attack)
- Separate counting for password failures and OTP failures
- Audit logging of all lockout and unlock events

**Super Administrator User Journey:**
1. Security monitoring shows a spike in account lockouts originating from a single IP range over the last hour. Super Admin opens the alert and drills into the locked-accounts view, filtering by that IP range.
2. Reviews the pattern: many different email addresses failing from the same IP in quick succession — a credential-stuffing attempt.
3. Adds the IP range to the deny list (see 6.1) with the description "Credential stuffing source — incident [ref]", stopping the traffic at the network edge.
4. The lockout spike stops. Super Admin then identifies a few legitimate users who were caught in the lockout (their own accounts, locked from their normal IP due to a shared network with the attacker).
5. For each legitimate user, Super Admin verifies their identity (registered details / OTP to registered phone) and performs one-click unlock, clearing the lockout counter.
6. The users can log in again; the unlock events are audit-logged with the acting admin and reason.
7. Super Admin reviews the incident summary in the audit trail: the failure pattern, the deny-list action, the unlocks, and the outcome, and records the incident as resolved.
8. Reviews the lockout configuration: confirms the progressive-lockout cap is sensible so a persistent attacker does not cause unbounded lockout durations for victims.

**Rules & Edge Cases:**
- Lockout counters reset after a successful login or after the lockout window elapses, whichever is relevant to the counter scope.
- Progressive lockout: each successive lockout within a defined period increases the duration (e.g., doubles), up to a cap, so persistent attacks face longer locks.
- OTP failures are counted separately from password failures, so a single bad or expired SMS does not lock the account's password path.
- Per-IP lockouts protect against attacks spanning many accounts; per-account lockouts protect a single targeted account; both can be active independently.
- One-click unlock by an admin always requires identity verification of the legitimate user and a recorded reason; it is audit-logged.
- All lockout and unlock events are audit-logged with account, IP, threshold crossed, duration, and (for unlocks) the acting admin.