# 5. Permission Auditing

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

---

## 5. Permission Auditing

### 5.1 View Permission Assignments per User
**What it does:** Provides a complete, current view of a user's effective access: every role they hold, each role's permission set, and the resulting effective permissions (features, actions, data scopes). This answers "what can this user do/see?" at a glance and is the starting point for access reviews, onboarding verification, and incident investigation.

**Sub-features:**
- Per-user access summary: roles held, each role's permissions, and the effective union
- Breakdown by module: which features, actions, and scopes the user effectively has
- Data-scope summary: the record sets the user can see per category
- Comparison view: the user's effective access vs. a reference role (to spot drift)
- Read-only view (changes go through the assignment/role-edit flows)
- Export of a user's access summary for reviews

**Super Administrator User Journey:**
1. A new teacher is onboarded. Super Admin opens the user's record and views the permission-assignment summary to verify onboarding was done correctly.
2. The summary shows: role Teacher/Content Creator; effective features (course creation, content upload, own analytics); data scope (own courses, own students).
3. Confirms the effective access matches the intended scope — no billing, no content approval, no other-institute data.
4. For a user whose access seems off, Super Admin uses the comparison view against the reference role: the user has an extra "export reports" permission from a second role they were assigned months ago.
5. Reviews the second role's necessity with the team lead and removes it if no longer needed (via Role Assignment).
6. Exports the user's access summary to attach to the onboarding record.
7. For an incident investigation, Super Admin pulls the affected user's access summary to establish exactly what they could reach at the time.
8. The view is read-only; every change it reflects is traceable to an audited assignment or role edit.

**Rules & Edge Cases:**
- The summary reflects current effective access (the union of held roles); historical access is available through the audit trail.
- Data-scope summaries show the scope definitions, not the full record lists.
- The comparison view surfaces drift (extra or missing permissions vs. a reference role) for right-sizing.
- The view is read-only; it does not grant or change access.
- Exports are access-controlled and the export action is audit-logged.
- The summary is consistent with what the user actually experiences (same permission model).

### 5.2 Audit Trail of Role and Permission Changes
**What it does:** Maintains a complete, tamper-evident history of every role and permission change: role creation, edits, deletion/archival, assignments, reassignments, removals, and permission-set modifications. Each entry records who changed what, from what to what, when, and from where — supporting compliance, forensics, and answering "who had access to X when?"

**Sub-features:**
- Event coverage: role create/edit/delete/archive, permission add/remove, role assign/reassign/remove, scope changes
- Each event: actor, action, target (role/user), before/after state, timestamp, IP, device
- Tamper-evidence: entries are immutable and integrity-checked
- Search and filter: by actor, action type, target role, target user, and time range
- Point-in-time reconstruction: what a role's permissions were, or what a user's roles were, at a given date
- Retention per compliance requirements
- Export for external audits

**Super Administrator User Journey:**
1. An auditor asks: "What permissions did the Billing Administrator role have on 1 March, and who changed it since?" Super Admin opens the Permission Audit Trail.
2. Filters by target role "Billing Administrator" and the date range from 1 March to now.
3. Reviews the entries: each shows the actor, the action (e.g., "removed: process refunds"), the before/after permission set, and the timestamp.
4. Uses the point-in-time view to reconstruct the role's permission set exactly as it was on 1 March.
5. Identifies the change that removed "process refunds" (actor, date, reason) and the subsequent creation of the Refunds Processor role.
6. Exports the filtered trail and the point-in-time snapshot in the auditor's required format.
7. Records the provision in the compliance log.
8. For a different question — "who could access invoices in June?" — Super Admin filters by the relevant permission and reviews which roles held it during June and who held those roles.

**Rules & Edge Cases:**
- The trail is immutable; no role can edit or delete entries, and alteration attempts are themselves logged and alerted.
- Before/after state is captured for every change, enabling exact reconstruction, not just detection.
- Point-in-time reconstruction answers "what was the state at date D" for both roles and users.
- Retention follows the strictest applicable regulation.
- Exports are read-only copies; the source trail remains authoritative.
- The trail covers all role/permission changes across all modules, not only this one.

### 5.3 Access Review Support
**What it does:** Supports periodic access reviews — the process of confirming that every user's access is still appropriate — with the views, exports, and tracking needed to run a review efficiently: current role-holder mappings, anomaly highlights, review records, and remediation tracking for findings.

**Sub-features:**
- Review workspace: role-holder mappings, per-user access summaries, and anomaly highlights in one place
- Anomaly detection: users with no roles, over-privileged users, stale holders (no recent activity), holders of archived roles
- Review record: date, scope, reviewer, findings, and outcomes per review cycle
- Remediation tracking: findings assigned to owners with due dates, tracked to closure
- Export of review evidence (mappings, summaries, changes made)
- Cadence reminders for recurring reviews

**Super Administrator User Journey:**
1. The quarterly access review is due; Super Admin receives the cadence reminder and opens the Access Review workspace.
2. Reviews the role-holder mappings for all sub-administrator roles, with holder counts, account status, and last-activity.
3. Works through the anomaly list: 2 users with no roles (assigned roles), 1 stale Billing Administrator (confirmed departed, role removed), 1 over-privileged user (right-sized the role set).
4. For each change, uses the assignment/role-edit flows (each individually audited).
5. Records the review: date, scope (all sub-admin roles), reviewer (Super Admin), findings (the anomalies), and outcomes (the changes made).
6. Assigns any open remediation items (e.g., "confirm institute X's staff roles by [date]") to owners with due dates.
7. Exports the review evidence — the mappings, the per-user summaries reviewed, and the changes made — for the compliance file.
8. Tracks remediation items to closure; the compliance dashboard shows the review as complete with no open findings.

**Rules & Edge Cases:**
- Reviews are recorded, not just performed: each cycle has a dated record with scope, reviewer, findings, and outcomes.
- Anomaly highlights reduce review effort but do not replace it; the full mapping is always available.
- Remediation items remain tracked until explicitly closed with evidence.
- Review evidence exports are access-controlled and the export action is audit-logged.
- Cadence reminders ensure reviews are not missed; the cadence is configurable.
- All changes made during a review are individually audit-logged and linked to the review record.

### 5.4 Separation of Duties Monitoring
**What it does:** Monitors role and permission combinations for separation-of-duties conflicts — situations where a single role, or a single user's combined roles, grants both a sensitive action and its approval (e.g., create discount codes and approve refunds, or configure the payment gateway and process payouts). Conflicts are flagged for review so the Super Administrator can make a deliberate, documented decision.

**Sub-features:**
- Conflict rule definitions: pairs/sets of permissions that should not be combined (e.g., create + approve, configure + execute)
- Role-level detection: a single role that grants a conflicting combination
- User-level detection: a user whose combined roles grant a conflicting combination
- Flag (not block): conflicts raise warnings for review, not automatic prevention
- Review workflow: acknowledge, decide (accept with justification or remediate), record the decision
- Audit logging of conflict flags and decisions

**Super Administrator User Journey:**
1. Super Admin is editing the Billing Administrator role and adds "Approve refunds." The editor immediately shows a separation-of-duties warning: "This role would grant both 'process refunds' and 'approve refunds'."
2. Reviews the warning and the conflict rule (refund processing and refund approval should be separated).
3. Decides to remediate: removes "Approve refunds" from the Billing Administrator role and assigns approval to a separate Finance Approver role held by a different person.
4. Saves; the warning clears, and the change is audit-logged.
5. In the user-level view, Super Admin reviews combined-role conflicts: one user holds both a role that creates discount codes and a role that approves promotions — a conflict.
6. Acknowledges the flag, discusses with the team lead, and right-sizes the user's roles (removes one of the conflicting roles), recording the decision.
7. For a conflict the business accepts (e.g., a small team where one person must hold both), Super Admin records an explicit acceptance with the justification and a review-by date.
8. Reviews the conflict dashboard monthly: open flags, accepted-with-justification items (and their review-by dates), and remediated items.

**Rules & Edge Cases:**
- Conflicts are flagged, not blocked — the Super Admin makes a deliberate, documented decision (remediate or accept with justification).
- Detection works at both the role level (a single role) and the user level (combined roles).
- Accepted conflicts require a justification and a review-by date; they are not silently ignored.
- Conflict rules are defined by the platform's separation-of-duties model and are visible to the Super Admin.
- Every flag, decision, and remediation is audit-logged.
- The monitoring is continuous: new conflicts appear as roles or assignments change, not only at review time.