# 4. Role-Based Access Control

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

---

## 4. Role-Based Access Control

### 4.1 Enforce Role-Based Access Across the Platform
**What it does:** Applies the role-to-permission mapping on every request across the entire platform — web interface and all underlying service surfaces — so that a user can only reach the features, perform the actions, and see the records their roles permit. This is the runtime enforcement behind role definition, assignment, and permission configuration: those define the rules, and RBAC enforcement makes them real on every request.

**Sub-features:**
- Per-request authorization check: user's roles → permissions → allowed/denied
- Consistent enforcement across web UI and service/API surfaces (same permission governs both)
- Deny-by-default: anything not explicitly permitted is denied
- Feature, action, and data-scope enforcement in a single check
- Prompt reflection of permission changes (next request, no re-login)
- Denial responses: clear user-facing message plus a logged denial event
- Super Administrator exemption: full access, not subject to the check

**Super Administrator User Journey:**
1. A Content Reviewer logs in. On every request — opening a section, loading a list, submitting an approval — the platform checks the reviewer's role permissions and allows only what is permitted.
2. The reviewer opens the review queue (permitted) and approves a content item (permitted action). Both succeed.
3. The reviewer attempts to open Pricing Management (not permitted). The request is denied server-side; the reviewer sees "You don't have permission to access this section."
4. Super Admin, monitoring the platform, sees the denial event in the access log: user, role, target, timestamp.
5. Super Admin changes the Content Reviewer role to add resource-library approval. The reviewer's next request reflects the new permission — no re-login.
6. A service-surface check: an attempt to call a billing operation for the reviewer (e.g., via a direct request) is denied by the same permission check, confirming enforcement is not UI-only.
7. Super Admin reviews a day's access decisions: allowed and denied counts by role and target, confirming enforcement matches the intended permission model.
8. The enforcement behavior is consistent for all user types (students, parents, staff, institutes) — the same RBAC mechanism applies, with each role's own permission set.

**Rules & Edge Cases:**
- Enforcement is per-request and server-side; the UI is shaped by permissions but is not the control.
- Deny-by-default: a missing permission mapping results in denial, never a silent allow.
- Permission changes take effect on the next request; there is no stale-permission window after a change.
- The same permission governs web and service surfaces, so there is no UI bypass.
- Denial events are logged with user, role, target, and timestamp for audit and misconfiguration detection.
- The Super Administrator role bypasses the check (full access); all other roles are subject to it.

### 4.2 Prevent Unauthorized Access to Features
**What it does:** Specifically guards the feature/section boundary: a user cannot open a section their roles do not permit, whether through the navigation, a direct URL, a bookmark, or a shared link. The prevention is server-side and produces a consistent, safe denial experience.

**Sub-features:**
- Section-level access check on every navigation and direct request
- Direct-URL and bookmark protection: unpermitted sections are denied regardless of how the address is reached
- Shared-link protection: a link to an unpermitted section does not grant access
- Consistent denial message with an optional "request access" path
- Denial logging with the attempted target
- No partial disclosure: a denied section reveals no data from it

**Super Administrator User Journey:**
1. A student shares a link to a course page they are enrolled in; a different student (not enrolled) opens the link. The course detail is denied for the second student (data scope), and the attempt is logged.
2. A support admin bookmarks the Marketing module from a period when they had access (before a permission change). After the change, opening the bookmark is denied with the standard message.
3. Super Admin reviews the denial log for the Marketing module: the support admin's attempt appears with role and timestamp, confirming the permission change is enforced.
4. A user with no access to a section receives the "request access" prompt; their request routes to Super Admin for review.
5. Super Admin reviews the access request, decides to grant the feature to the user's role (or deny), and records the decision.
6. If granted, the user's next attempt to the section succeeds; if denied, the user is informed of the decision.
7. Super Admin periodically reviews the "request access" queue to keep it clear and to spot roles that are frequently requesting the same feature (a signal to update the role's default set).
8. All denials and access requests are audit-logged.

**Rules & Edge Cases:**
- A denied section reveals no data from it — no partial disclosure, no metadata leakage.
- Direct URLs, bookmarks, and shared links are all subject to the same check; reachability never implies permission.
- The denial message is consistent and does not reveal why beyond "not permitted" (avoiding enumeration).
- "Request access" is optional per policy; where enabled, requests route to Super Admin with the requester and target.
- Denials are logged; a pattern of repeated denials for a role/target is a misconfiguration or misuse signal.
- The check applies to authenticated users; unauthenticated requests are handled by the login flow, not RBAC.

### 4.3 Prevent Unauthorized Access to Data
**What it does:** Guards the record boundary: even within a section a user can open, they can see and act only on the records their roles' data scopes permit. This prevents a user from reaching another user's records (another teacher's courses, another institute's students, another user's invoices) through IDs, search, or exports.

**Sub-features:**
- Record-level scope check on every read, write, search, and export
- ID-based access protection: guessing or entering a record ID outside the user's scope is denied
- Search and list scoping: results contain only in-scope records
- Export scoping: exports include only in-scope records
- Cross-institute isolation: one institute's records are not reachable by another institute's users
- Denial logging for out-of-scope record attempts
- Consistent with feature enforcement (same per-request check)

**Super Administrator User Journey:**
1. A teacher opens their course list: only their assigned courses appear (scope: own records).
2. The teacher enters a course ID of a colleague's course in the URL. The record is denied (out of scope), and the attempt is logged.
3. The teacher runs a search for a student by name; results are limited to students in the teacher's scoped courses, not the whole platform.
4. The teacher exports their course's enrollment list; the export contains only in-scope students.
5. An institute A staff member attempts to access an institute B student record by ID; denied (cross-institute isolation), and logged.
6. Super Admin reviews the out-of-scope attempt log: the teacher's ID-guess and the cross-institute attempt appear with user, target, and timestamp.
7. Super Admin assesses the attempts: the ID-guess is likely accidental (a shared link), the cross-institute attempt is reviewed for intent; both are resolved and noted.
8. The scoping behavior is verified in the quarterly access review: sample users in each role see exactly their intended record sets.

**Rules & Edge Cases:**
- Record scope is enforced on reads, writes, searches, and exports — no path bypasses it.
- Out-of-scope record access by ID is denied and logged (supports detecting probing).
- Cross-institute isolation is a hard scope boundary; it is not configurable per user.
- Search and list results never include out-of-scope records (no leakage through result sets).
- Exports respect the same scope as the on-screen view.
- All out-of-scope attempts are audit-logged with user, target record, and timestamp.

### 4.4 Access Denial Logging and Review
**What it does:** Records every access denial (feature or data) with full context and provides review views so the Super Administrator can confirm enforcement is working, spot misconfigured roles, detect probing or misuse, and answer access questions. Denial logging turns RBAC enforcement into an auditable, reviewable signal.

**Sub-features:**
- Denial event fields: user, role(s), target (feature or record), request type, timestamp, IP, device
- Real-time and historical denial views with filters (by user, role, target, type, time)
- Pattern detection: repeated denials for a user/role/target (misconfiguration or misuse)
- Probing indicator: many distinct out-of-scope record IDs attempted by one user
- Link from a denial to the user's role set and the target's required permission
- Export of denial logs for audits
- Retention per policy

**Super Administrator User Journey:**
1. Super Admin opens the Access Denial view in Role & Permission Management (or Security Monitoring) and reviews the last 24 hours of denials.
2. Filters by target "Pricing Management": a support admin has 12 denials in an hour. Super Admin opens the pattern view — this looks like the user is trying to reach a section they were told they couldn't use.
3. Reviews the user's role set and the target's required permission, confirming the role genuinely lacks the feature (not a misconfiguration).
4. Contacts the user to understand the need; if legitimate, grants the feature to the role (with preview) or explains the restriction.
5. Filters by user for a teacher who shows 30 distinct out-of-scope course-ID attempts in an hour — a probing pattern. Super Admin reviews the attempts, determines intent (accidental vs. deliberate), and takes action (coaching, or suspension if deliberate).
6. For a role that is repeatedly hitting denials on a feature many of its holders need, Super Admin updates the role's default permission set to include the feature, clearing the recurring denials.
7. Exports the denial log for the security audit evidence package.
8. Reviews the denial trends monthly: volume by type, top targets, and resolved vs. open items.

**Rules & Edge Cases:**
- Denial events are append-only and retained per policy; they cannot be edited or deleted.
- A denial reveals nothing about the protected resource beyond the standard denial message.
- Pattern detection (repeated denials, probing) raises review items; it does not automatically block (blocking is a separate control).
- The link from denial to required permission makes misconfiguration vs. misuse distinguishable quickly.
- Exports are access-controlled and the export action is audit-logged.
- Denial logging covers both feature and data denials in one reviewable stream.