# 2. Role Assignment

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

---

## 2. Role Assignment

### 2.1 Assign Roles to User Accounts
**What it does:** Binds a role to a user account, granting the user the role's permissions. Assignment is the mechanism through which access is actually given: a user's effective access is the union of the permissions of all roles they hold. The Super Administrator assigns roles individually or in bulk, with validation and immediate effect.

**Sub-features:**
- Assign one or more roles to a user from the user record or the role's holder view
- Bulk assignment: apply a role to a selected group of users (e.g., a new cohort of teachers)
- Active-role-only picker: only active roles can be assigned
- Immediate effect: the user's access updates on their next request
- Optional notification to the user on role assignment (per policy)
- Audit logging of every assignment with actor, user, role, and timestamp

**Super Administrator User Journey:**
1. A new teacher joins an institute. Super Admin opens the user's record in the user directory and selects "Assign role".
2. The role picker shows only active roles. Super Admin selects Teacher/Content Creator.
3. Confirms the assignment; the user's effective access now includes the role's permissions from the next request.
4. The teacher logs in and sees the sections their role permits (course creation, content upload, their own analytics).
5. For a bulk case — 15 new staff at a new institute — Super Admin selects the 15 users in the user directory, chooses "Assign role", picks the appropriate role for each group (teachers, reviewers, billing), and confirms the bulk preview: "15 users — 10 teachers, 4 reviewers, 1 billing."
6. The bulk assignment applies; each user's access updates on their next request.
7. Super Admin spot-checks one user from each group to verify the correct access.
8. All assignments (individual and bulk) are audit-logged with the actor, users, roles, and timestamp.

**Rules & Edge Cases:**
- Only active roles can be assigned; archived roles are excluded from the picker.
- A user can hold multiple roles; effective access is the union of their permissions (data scoping still applies per the scoping rules).
- Assignment takes effect on the user's next request; no re-login is required.
- Bulk assignments require a confirmed preview of the affected users and roles.
- Every assignment is audit-logged; bulk assignments are logged as a batch with the member list.
- Assigning a role does not create the user account; the user must already exist (see User Account Management).

### 2.2 Reassign or Remove Roles
**What it does:** Changes a user's role composition over time: removing a role (revoking its permissions), replacing one role with another (reassignment), or adjusting the full set. This is the primary tool for role changes, departures, and access right-sizing, with immediate effect and full audit.

**Sub-features:**
- Remove a single role from a user (revokes that role's permissions on the next request)
- Reassign: replace one role with another in a single action (old removed, new added)
- Review the user's full role set before and after the change
- Guardrail: a user cannot be left with no roles if the account requires at least one (configurable)
- Immediate effect on the next request
- Audit logging of every removal/reassignment with before/after role sets

**Super Administrator User Journey:**
1. A Content Reviewer is promoted to a lead role that also manages scheduling. Super Admin opens the user's record and reviews their current role set: Content Reviewer.
2. Selects "Reassign" and chooses the new role (e.g., a custom "Content Lead" role) to replace Content Reviewer.
3. Reviews the before/after: loses the reviewer-only permissions, gains the lead's permissions (which include review plus scheduling).
4. Confirms; the change applies on the user's next request. The user's navigation updates to reflect the new access.
5. For a departing staff member, Super Admin removes all roles from the account (or suspends the account — see Authentication & Access), revoking all role-based access immediately.
6. The removal is audit-logged with the before/after role sets, the actor, and the reason.
7. Super Admin reviews the user's access afterward to confirm only the intended roles remain.
8. For a user who should keep their role but lose one capability, Super Admin edits the role (if it affects others) or creates a tailored role — choosing the least-blast-radius option.

**Rules & Edge Cases:**
- Role removal revokes the role's permissions on the user's next request; in-progress actions complete but new actions with the removed permission are denied.
- Reassignment is atomic: the old role is removed and the new one added in one audited action.
- Where policy requires every active user to hold at least one role, removing the last role is blocked with a prompt to reassign instead.
- Every change is audit-logged with before/after role sets.
- Removing a role does not deactivate the user account; account status is a separate control.
- Changes take effect without re-login.

### 2.3 Track Role Holders
**What it does:** Provides a clear, queryable view of who holds which roles — from both directions: the role's holder list (all users with a given role) and the user's role set (all roles a given user holds). This supports access reviews, staffing questions, and the reassignment workflow.

**Sub-features:**
- Role → Users view: all holders of a role with their account status and last-activity
- User → Roles view: all roles held by a user with each role's permission summary
- Filters: by role, by user type, by account status, by institute (where applicable)
- Search by user name/email or role name
- Export of the role-holder mapping for access reviews
- Highlight of anomalies: users with no roles, users with unusually many roles, holders of archived roles

**Super Administrator User Journey:**
1. For the quarterly access review, Super Admin opens Role & Permission Management → Role Holders.
2. Reviews the role → users view for each sub-administrator role: holder count, account status, last-activity.
3. Notices a Billing Administrator whose last-activity is 60 days old (possibly a departed staff member). Opens the user's record, confirms with the institute that the person has left, and removes the role (or suspends the account).
4. Reviews the anomaly list: 2 users with no roles (new accounts not yet assigned) and 1 user holding 4 roles (possible over-privileging).
5. Assigns roles to the 2 unassigned users and reviews the 4-role user with the team lead to right-size the set.
6. Exports the role-holder mapping for the access-review record.
7. Records the review outcome (changes made, items cleared) in the compliance log.
8. Repeats the review on a fixed cadence; the anomaly highlights make each pass quick.

**Rules & Edge Cases:**
- The mapping reflects current state; historical holder data is available through the audit trail.
- Holders of archived roles are highlighted so they can be reassigned.
- Users with no roles are highlighted (they have no role-based access; deny-by-default).
- Exports are access-controlled and the export action is audit-logged.
- The view is read-only; changes are made through the assignment/reassignment flows.
- Data scoping means two holders of the same role may see different records; the holder view shows role membership, not per-user data scope.

### 2.4 Multiple Roles per User
**What it does:** Defines how a user's access is computed when they hold more than one role: the effective permission set is the union of all held roles' permissions, with data scoping applied per the scoping rules. This supports users who wear multiple hats (e.g., a teacher who also reviews content) while keeping the union behavior predictable and auditable.

**Sub-features:**
- Union of permissions across held roles (a permission granted by any held role is available)
- Data scoping: where roles scope data differently, the scoping rules define the effective scope (typically the union of visible records, per policy)
- Role-set view per user showing each role and its contribution
- Conflict handling: where roles grant overlapping but differently-scoped access, the policy-defined resolution applies
- Right-sizing guidance: highlight users whose role set is broader than typical for their function
- Audit logging of role-set changes

**Super Administrator User Journey:**
1. A teacher is also asked to review content for their department. Super Admin assigns the Content Reviewer role in addition to the existing Teacher/Content Creator role.
2. The user's effective access is now the union: they can create content (teacher) and review/approve content (reviewer), with data scoping per each role's rules.
3. Super Admin reviews the user's role-set view: both roles listed, each with its permission summary and the resulting union.
4. Confirms the union is the intended access and that no billing or platform-setting permissions have crept in.
5. Later, during an access review, the right-sizing highlight flags this user (2 roles) alongside other multi-role users. Super Admin confirms with the team lead that the dual role is still needed.
6. Where a user's roles create an unexpectedly broad union (e.g., a role combination that grants both discount creation and refund approval), the separation-of-duties flag raises a warning for review.
7. Super Admin documents the decision (keep or right-size) and makes any change through the reassignment flow.
8. All role-set changes are audit-logged with the before/after sets.

**Rules & Edge Cases:**
- Effective access is the union of held roles' permissions; removing a role removes only the permissions not also granted by another held role.
- Data scoping is applied per the policy-defined resolution where roles scope differently; the default is the union of visible records.
- Over-privileging is surfaced through right-sizing highlights, not silently enforced.
- Separation-of-duties conflicts across a user's combined roles are flagged for review (e.g., the union grants both a sensitive action and its approval).
- The role-set view makes the union transparent so access questions can be answered from the UI.
- All role-set changes are audit-logged.