Security architecture

This document provides a complete overview of the Makronexus security model. It covers the recommended role structure, permission matrix, and security best practices for schools of all sizes.

---

Security model overview

┌─────────────────────────────────────────────────────────────────────────┐
│                    Makronexus Security Architecture                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                      Authentication Layer                          │  │
│  │                                                                    │  │
│  │   Login → MFA → Device Trust → Session Management                  │  │
│  │                                                                    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                    │                                     │
│                                    ▼                                     │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                      Authorization Layer                           │  │
│  │                                                                    │  │
│  │   Users → Roles → Permissions → ABAC Policies → Resource Grants   │  │
│  │                                                                    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                    │                                     │
│                                    ▼                                     │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                        Audit Layer                                 │  │
│  │                                                                    │  │
│  │   Activity Logs → Alerts → Compliance Exports → Retention          │  │
│  │                                                                    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Core security components

Component	Purpose	Documentation
Identity & Access	Users, roles, permissions, policies	IAM Guide
Sessions & MFA	Session management, multi-factor auth	Sessions Guide
Device Trust	Trusted device management	Sessions Guide
Audit & Compliance	Activity logging, exports	Audit Guide

---

Recommended role structure

System roles (built-in)

These roles are predefined and available in every tenant:

Role	Description	Typical users
Super Admin	Full platform access	Platform operators
Tenant Admin	Full tenant access	IT administrators
School Admin	Full school access	Principals, vice principals
Teacher	Classroom operations	Teachers, instructors
Bursar	Financial operations	Finance staff
Registrar	Student records	Admissions, records staff
Guardian	Parent portal	Parents, guardians
Student	Student self-service	Students

Role hierarchy

Super Admin (Platform)
    │
    └── Tenant Admin (Multi-school)
            │
            └── School Admin (Single school)
                    │
                    ├── Academic roles:
                    │   ├── Teacher
                    │   └── Registrar
                    │
                    ├── Finance roles:
                    │   └── Bursar
                    │
                    └── Portal roles:
                        ├── Guardian
                        └── Student

---

Permission matrix

Academic permissions

Permission	Super Admin	Tenant Admin	School Admin	Teacher	Registrar	Guardian	Student
students.view	✓	✓	✓	✓	✓	Own	Self
students.create	✓	✓	✓	–	✓	–	–
students.update	✓	✓	✓	–	✓	–	–
students.delete	✓	✓	✓	–	–	–	–
students.import	✓	✓	✓	–	✓	–	–
gradebooks.view	✓	✓	✓	Own	–	Own	Self
gradebooks.update	✓	✓	✓	Own	–	–	–
attendance.view	✓	✓	✓	Own	✓	Own	Self
attendance.update	✓	✓	✓	Own	–	–	–

Financial permissions

Permission	Super Admin	Tenant Admin	School Admin	Teacher	Bursar	Guardian	Student
finance.view	✓	✓	✓	–	✓	Own	Own
finance.payments	✓	✓	✓	–	✓	–	–
finance.invoices	✓	✓	✓	–	✓	–	–
finance.reports	✓	✓	✓	–	✓	–	–
fees.manage	✓	✓	✓	–	✓	–	–

Administrative permissions

Permission	Super Admin	Tenant Admin	School Admin	Teacher	Registrar	Bursar
users.view	✓	✓	✓	–	–	–
users.manage	✓	✓	✓	–	–	–
roles.view	✓	✓	✓	–	–	–
roles.manage	✓	✓	–	–	–	–
settings.view	✓	✓	✓	–	–	–
settings.manage	✓	✓	✓	–	–	–
audit.view	✓	✓	✓	–	–	–

Security permissions

Permission	Super Admin	Tenant Admin	School Admin
sessions.view	✓	✓	✓
sessions.terminate	✓	✓	✓
mfa.manage	✓	✓	✓
devices.manage	✓	✓	✓
audit.export	✓	✓	✓
policies.manage	✓	✓	–

---

Role configurations by school size

Small school (< 200 students)

Role	Staff count	Notes
School Admin	1-2	Principal handles admin
Teacher	5-15	All teachers same role
Bursar	1	May be shared with admin
Registrar	1	May be shared with teacher

Recommended:

• Use system roles without customization
• Principal as School Admin
• Secretary can have Registrar + limited Bursar

Medium school (200-1000 students)

Role	Staff count	Notes
School Admin	2-4	Principal + VPs
Teacher	15-50	Separate by department
Bursar	2-5	Dedicated finance team
Registrar	2-4	Dedicated records team

Recommended:

• Consider custom roles for department heads
• Separate finance from academics
• Add "Read-only" variants for oversight

Large school (> 1000 students)

Role	Staff count	Notes
School Admin	5+	Leadership team
Teacher	50+	Tiered by seniority
Bursar	5+	Specialized finance roles
Registrar	5+	Specialized records roles

Recommended:

• Create custom roles for:
  • Department Head (Teacher + some admin)
  • Senior Teacher (Teacher + mentoring)
  • Finance Manager (Bursar + reports)
  • Data Entry (limited Registrar)
• Use ABAC policies for fine-grained control

---

Custom role examples

Department head

Base: Teacher role
Additional permissions:
- students.view (all in department)
- gradebooks.view (department overview)
- teachers.view (department only)
- reports.department

Finance manager

Base: Bursar role
Additional permissions:
- finance.reports (all)
- finance.budgets
- audit.view (finance only)

Data entry clerk

Limited permissions:
- students.create
- students.update (basic fields only)
- students.import

Read-only auditor

View-only permissions:
- students.view
- finance.view
- gradebooks.view
- audit.view
No create/update/delete

---

Security configuration checklist

Authentication setup

• Configure password policy (min 8 chars, complexity)
• Enable MFA for all admin accounts
• Set session timeout (30 min idle, 8 hours max)
• Configure account lockout (5 attempts, 30 min lock)
• Enable login notifications

Authorization setup

• Review and customize system roles
• Create custom roles for specialized staff
• Define ABAC policies for sensitive operations
• Set up resource grants for school-specific access
• Test permission matrix with sample users

Audit setup

• Enable all audit categories
• Configure retention policies
• Set up critical alerts
• Schedule compliance exports
• Test audit log access

Device trust setup

• Define trusted device policy
• Set maximum devices per user
• Configure re-verification period
• Enable compromise detection
• Document device management process

---

Onboarding security checklist

New school setup

1. Create school admin accounts

   • Principal → School Admin role
   • IT contact → Tenant Admin (if multi-school)
   • Document emergency access

2. Configure basic roles

   • Review Teacher role permissions
   • Review Bursar role permissions
   • Review Registrar role permissions
   • Adjust for school needs

3. Set security policies

   • Password requirements
   • Session timeouts
   • MFA requirements

4. Test access patterns

   • Test each role type
   • Verify portal access
   • Test mobile access

New staff member

1. Create user account
2. Assign appropriate role(s)
3. Set organization scope
4. Send welcome email
5. Guide MFA setup
6. Verify access works

Departing staff member

1. Deactivate account (don't delete)
2. Terminate all active sessions
3. Remove role assignments
4. Revoke trusted devices
5. Note departure in audit
6. Review any data they exported

---

Security incident response

Suspected compromise

1. Contain

   • Terminate all user sessions
   • Deactivate suspected accounts
   • Revoke trusted devices

2. Investigate

   • Review audit logs
   • Check login attempts
   • Identify affected resources

3. Remediate

   • Reset passwords
   • Re-enable MFA
   • Review permissions

4. Document

   • Record incident details
   • Export relevant logs
   • Update policies if needed

Unauthorized access

1. Identify scope of access
2. Terminate active sessions
3. Review what was accessed
4. Notify affected users
5. Document and report

---

Compliance requirements

FERPA (Education records)

Requirement	Implementation
Access control	Role-based permissions
Audit trail	All data access logged
Directory information	Separate permission
Parent access	Guardian role

GDPR (If applicable)

Requirement	Implementation
Consent	Tracked in student record
Right to access	Export feature
Data retention	Retention policies
Breach notification	Alert system

SOC 2

Requirement	Implementation
Security	MFA, encryption, access control
Availability	Session management
Processing integrity	Audit logs
Confidentiality	Role permissions

---

Best practices summary

Role management

• Start with system roles
• Create custom roles only when needed
• Use descriptive role names
• Document role purposes
• Review roles quarterly

Permission management

• Follow least privilege
• Prefer role assignment over direct
• Audit permission changes
• Test before deploying

Session management

• Enforce MFA for admins
• Set reasonable timeouts
• Monitor active sessions
• Review login patterns

Audit management

• Review logs weekly
• Respond to alerts promptly
• Export for compliance
• Retain per policy

---

Quick reference

Navigation paths

Module	Path
Users	Foundation → IAM → Users
Roles	Foundation → IAM → Roles
Permissions	Foundation → IAM → Permissions
Policies	Foundation → IAM → Policies
Sessions	Foundation → Security → Sessions
MFA	Foundation → Security → MFA
Devices	Foundation → Security → Device Trust
Audit Logs	Foundation → Audit → Logs
Alerts	Foundation → Audit → Alerts
Exports	Foundation → Audit → Exports

Common tasks

Task	Steps
Add user	Users → Add → Fill form → Assign role
Create role	Roles → Create → Name → Add permissions
Reset MFA	Users → [User] → Security → Reset MFA
View sessions	Security → Sessions → Filter
Export audit	Audit → Exports → New → Configure

---

Related documentation

• Identity & access management — Detailed IAM guide
• Sessions, MFA & device trust — Security controls
• Audit & compliance — Logging and exports
• Common permission issues — Troubleshooting