Identity & access management

Identity & Access Management (IAM) is the security foundation of Makronexus. It controls who can sign in, what they can do, and which resources they can access. The system implements Role-Based Access Control (RBAC) with Attribute-Based Access Control (ABAC) policies for fine-grained authorization.

---

Navigation path

Foundation → Identity & Access (segment: foundation/iam)

Sub-section	Path	Description
Users	foundation/iam/users	User account management
Roles	foundation/iam/roles	Role definitions and assignments
Permissions	foundation/iam/permissions	Action-level access control
Policies	foundation/iam/policies	ABAC conditional rules
Resources	foundation/iam/resources	Protected resource instances

---

IAM architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         Identity & Access Management                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────┐   │
│  │    Users     │───→│    Roles     │───→│      Permissions         │   │
│  │  (Identities)│    │  (Bundles)   │    │  (resource.action)       │   │
│  └──────────────┘    └──────────────┘    └──────────────────────────┘   │
│         │                   │                        │                   │
│         │                   ▼                        │                   │
│         │           ┌──────────────┐                 │                   │
│         │           │   Policies   │←────────────────┘                   │
│         │           │  (ABAC Rules)│                                     │
│         │           └──────────────┘                                     │
│         │                   │                                            │
│         ▼                   ▼                                            │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    Resource Grants                                │   │
│  │   (User → Resource Instance → Permitted Actions)                  │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Part 1: Users

Users are login identities that access the system through email/username authentication.

User properties

Field	Type	Description
id	string	Unique identifier
tenantId	string	Tenant association
email	string	Primary email (login)
username	string	Optional username
phone	string	Contact phone
firstName	string	First name
lastName	string	Last name
displayName	string	Display name
emailVerified	boolean	Email confirmed
authProvider	enum	Authentication method
isActive	boolean	Account active status
roles	array	Assigned roles
lastLoginAt	datetime	Last successful login
lockedUntil	datetime	Account lock expiry
loginAttempts	number	Failed login count

Authentication providers

Provider	Description
local	Email/password authentication
google	Google OAuth
microsoft	Microsoft/Azure AD
saml	Enterprise SAML SSO
ldap	LDAP/Active Directory

User management actions

Action	Description	Permission
Create	Add new user	users.create
View	View user details	users.view
Edit	Update user profile	users.update
Delete	Remove user account	users.delete
Activate	Enable user access	users.activate
Deactivate	Disable user access	users.deactivate
Unlock	Remove account lock	users.unlock
Reset password	Trigger password reset	users.reset_password

Bulk user operations

Operation	Description
activate	Bulk activate users
deactivate	Bulk deactivate users
suspend	Bulk suspend users
unlock	Bulk unlock accounts
delete	Bulk delete users
verify_email	Bulk verify emails
reset_password	Bulk password reset
assign_role	Bulk role assignment
remove_role	Bulk role removal
update_org_unit	Bulk org unit change

Creating a user

1. Navigate to Foundation → Identity & Access → Users
2. Click Add User
3. Fill required fields:
   • Email (required)
   • First name, Last name
   • Authentication provider
4. Optional: Assign roles immediately
5. Optional: Send welcome email
6. Save user

---

Part 2: Roles

Roles bundle permissions into reusable access profiles that can be assigned to users.

Role properties

Field	Type	Description
id	string	Unique identifier
tenantId	string	Tenant scope
name	string	Role name
description	string	Role purpose
isSystem	boolean	System-defined role
isActive	boolean	Role active status
permissionCount	number	Assigned permissions
userCount	number	Users with this role
assignmentCount	number	Total assignments

System roles

System roles are predefined and cannot be deleted:

Role	Description
Super Admin	Full system access
Tenant Admin	Full tenant access
School Admin	School-level administration
Teacher	Teaching and grading
Bursar	Financial operations
Registrar	Student records
Guardian	Parent/guardian portal
Student	Student self-service

Role management actions

Action	Description
Create role	Define new role
Edit role	Update role details
Delete role	Remove custom role
Clone role	Duplicate role
Assign permissions	Add permissions to role
Remove permissions	Remove permissions from role
Assign to user	Give user this role

Role assignment properties

Field	Description
roleId	Role being assigned
userId	User receiving role
organizationUnitId	Scope (school, department)
assignedBy	Admin who assigned
assignedAt	Assignment timestamp
expiresAt	Optional expiry date
isActive	Assignment status

Creating a role

1. Navigate to Foundation → Identity & Access → Roles
2. Click Create Role
3. Enter role name and description
4. Select permissions to include
5. Save role

Assigning a role to a user

1. Navigate to user profile or role details
2. Click Assign Role / Add User
3. Select user or role
4. Optionally set organization scope
5. Optionally set expiry date
6. Save assignment

---

Part 3: Permissions

Permissions are granular action authorizations in the format resource.action.

Permission structure

permission = resource + "." + action

Examples:
- students.create     → Create student records
- students.view       → View student data
- students.update     → Edit student data
- students.delete     → Delete student records
- finance.view        → View financial data
- finance.payments    → Process payments
- reports.export      → Export reports

Permission properties

Field	Type	Description
id	string	Unique identifier
name	string	Permission name
resource	string	Resource category
action	string	Action type
description	string	Purpose description
isSystem	boolean	System-defined
roleCount	number	Roles using this
userCount	number	Users with this

Common resource categories

Resource	Description
students	Student records
teachers	Staff records
users	User accounts
roles	Role management
permissions	Permission management
finance	Financial module
admissions	Admissions module
attendance	Attendance tracking
gradebooks	Grade management
reports	Report generation
analytics	Analytics dashboards
audit	Audit logs
settings	System settings

Common actions

Action	Description
view	Read access
create	Create new records
update	Modify existing records
delete	Remove records
export	Export data
import	Import data
approve	Approve workflows
manage	Full management

Permission check result

Property	Description
allowed	Access granted
source	How permission was granted

Source	Description
direct	Assigned directly to user
role	Inherited from role
system	System-level access

---

Part 4: Policies (ABAC)

Policies implement Attribute-Based Access Control for conditional, context-aware authorization.

Policy properties

Field	Type	Description
id	string	Unique identifier
name	string	Policy name
description	string	Policy purpose
version	number	Policy version
isActive	boolean	Policy status
resource	string	Target resource
action	string	Target action
effect	enum	Allow or deny
condition	object	Evaluation rules
priority	number	Evaluation order
tags	array	Classification tags

Policy effects

Effect	Description
allow	Grant access when conditions match
deny	Block access when conditions match

Condition operators

Operator	Description	Example
and	All conditions must match	User is admin AND resource is active
or	Any condition can match	User is owner OR user is admin
not	Negation	User is NOT suspended
equals	Exact match	status == "active"
notEquals	Not equal	role != "guest"
contains	String contains	email contains "@school.edu"
in	Value in list	role in ["admin", "manager"]
notIn	Value not in list	status notIn ["deleted", "archived"]
greaterThan	Numeric comparison	balance > 0
lessThan	Numeric comparison	attempts < 5
greaterThanOrEqual	Numeric comparison	grade >= 60
lessThanOrEqual	Numeric comparison	age <= 18

Policy evaluation context

Context	Description
Subject	User making the request
Resource	Object being accessed
Action	Operation being performed
Environment	Time, location, etc.

Example policy

{
  "name": "School Admin Own School Only",
  "description": "School admins can only manage their own school",
  "resource": "schools",
  "action": "update",
  "effect": "allow",
  "condition": {
    "operator": "equals",
    "attribute": "subject.schoolId",
    "comparison": "resource.id"
  },
  "priority": 100
}

Creating a policy

1. Navigate to Foundation → Identity & Access → Policies
2. Click Create Policy
3. Enter name and description
4. Select target resource and action
5. Choose effect (allow/deny)
6. Define conditions
7. Set priority
8. Save policy

---

Part 5: Resources and grants

Resources represent protected objects, and grants control access to specific instances.

Resource categories

Category	Description
core	Core system resources
organization	Organizational units
security	Security resources
data	Data resources
system	System resources
custom	Custom resources

Resource type definition

Property	Description
type	Resource type identifier
name	Human-readable name
description	Resource description
category	Resource category
module	Owning module
permissions	Available permissions
isHierarchical	Supports hierarchy
isSystem	System-defined

Resource instances

Property	Description
id	Instance ID
resourceType	Type reference
resourceId	External ID
displayName	Display name
description	Instance description
parentId	Parent instance (hierarchy)
isActive	Active status

Grants

Grants link users to specific resource instances with permitted actions:

Grant = User + Resource Instance + Actions

---

How access control works

Request flow

User Request
     │
     ▼
┌─────────────────┐
│ 1. Authenticate │ ← Verify identity
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. Load Context │ ← User, roles, policies
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. Check Perms  │ ← Role-based permissions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. Eval Policies│ ← ABAC conditions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. Check Grants │ ← Resource-specific
└────────┬────────┘
         │
         ▼
    ALLOW / DENY

UI enforcement

The system enforces access at multiple layers:

Layer	Enforcement
Navigation	Menu items hidden if no access
Tabs	Tabs hidden if no module access
Buttons	Disabled if action not permitted
Fields	Read-only if no edit permission
API	Requests rejected if unauthorized

---

Permissions required

Action	Required permission
View users	users.view
Create users	users.create
Edit users	users.update
Delete users	users.delete
View roles	roles.view
Manage roles	roles.manage
View permissions	permissions.view
Manage permissions	permissions.manage
View policies	policies.view
Manage policies	policies.manage

---

Best practices

User management

• Use unique email addresses per user
• Deactivate (don't delete) departing staff
• Review inactive accounts quarterly
• Enforce strong passwords

Role design

• Create roles based on job functions
• Use principle of least privilege
• Don't grant more access than needed
• Review role assignments regularly

Permission assignment

• Prefer role-based over direct assignment
• Document custom permission grants
• Audit permission changes monthly

Policy management

• Test policies in development first
• Use meaningful names and descriptions
• Set appropriate priorities
• Document policy decisions

---

Troubleshooting

Missing buttons or tabs

Cause: Permission not granted Fix: Check user's roles and permissions

"Access denied" error

Cause: Multiple possibilities

• No permission for action
• Wrong school selected
• Policy blocking access
• Session expired

Fix:

1. Verify school selection
2. Check role assignments
3. Review applicable policies
4. Re-authenticate if needed

User cannot sign in

Cause: Multiple possibilities

• Account deactivated
• Account locked
• Password expired
• MFA not configured

Fix:

1. Check isActive status
2. Check lockedUntil field
3. Reset password if needed
4. Configure MFA if required

Role not taking effect

Cause: Assignment not active Fix: Verify assignment is active and not expired

---

Related documentation

• Sessions, MFA & device trust — Authentication security
• Audit & compliance — Activity tracking
• Security overview — Security architecture