Skip to main content

Identity and Access Management Architecture

Purpose​

This document describes the authentication, authorization, and access management architecture of Chilarai.

It defines:

  • Identity model
  • Authentication model
  • Authorization model
  • School context model
  • Role model
  • Permission model
  • Scope model
  • Navigation security
  • API security
  • Future agent authorization

This document is intended to be implementation-oriented and should be used as the primary reference when building identity and authorization features.

Architectural Principles​

Authentication and Authorization are Separate Concerns​

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to do?

Authentication is provided by Keycloak.

Authorization is provided by Chilarai.

School Membership is the Security Boundary​

Users do not directly receive permissions.

Users receive permissions through School Memberships.

User
    ↓
School Membership
    ↓
Roles
    ↓
Permissions

A user's access is always evaluated within a School Context.

Permissions Drive Access​

Roles are administrative constructs.

Permissions determine access.

Examples:

students.read
students.manage

attendance.read
attendance.manage

fees.read
fees.manage

All security decisions are ultimately permission-based.

Permissions and Scopes are Independent​

Permissions determine:

What can be done?

Scopes determine:

On which data can it be done?

Examples:

students.read

may operate with:

school
assigned-sections
own-children

depending on the role configuration.

Backend is the Security Authority​

Frontend authorization is for user experience only.

The backend is responsible for all security enforcement.

Access must never rely on frontend checks.

Identity Architecture

High-Level Model​

Keycloak
    ↓
Authentication
    ↓
User
    ↓
School Membership
    ↓
Role
    ↓
Permission + Scope

Identity Ownership​

Keycloak Owns​

Authentication concerns.

Examples:

  • Login
  • Password
  • MFA
  • Session Management
  • Token Issuance
  • Account Recovery

Chilarai Owns​

Application authorization concerns.

Examples:

  • User Profile
  • Schools
  • Memberships
  • Roles
  • Permissions
  • Scopes
  • School Context

Core Entities

User​

Represents a platform identity.

A User may belong to multiple Schools.

Examples:

  • Parent
  • Teacher
  • Principal
  • Accountant
  • Platform Administrator

Attributes​

UserId
KeycloakUserId
Email
FirstName
LastName
Status

School​

Represents a business entity.

Authorization is always evaluated within a School.

Attributes​

SchoolId
SchoolName

School Membership​

Represents a User's relationship with a School.

This is the primary authorization boundary.

Attributes​

MembershipId
UserId
SchoolId
Status

Relationships​

User
    ↓
School Membership
    ↓
Roles

A user may have different memberships in different schools.

Role​

Represents a responsibility within a School.

Examples:

Teacher
Parent
Principal
SchoolAdmin
Accountant
Receptionist

Roles are permission bundles.

Roles do not directly grant access.

Roles grant Permission + Scope combinations.

Attributes​

RoleId
Name
Description

Permission​

Represents an operation.

Permissions answer:

What can be done?

Naming Convention​

<resource>.read
<resource>.manage

Examples:

students.read
students.manage

admissions.read
admissions.manage

attendance.read
attendance.manage

fees.read
fees.manage

staff.read
staff.manage

schools.read
schools.manage

Permission Levels​

Chilarai intentionally uses a simple permission model.

Read​

Allows viewing information.

Examples:

students.read
fees.read
attendance.read

Includes:

  • View
  • Search
  • Filter
  • Export

Manage​

Allows performing modifications.

Examples:

students.manage
attendance.manage
fees.manage

Includes:

  • Create
  • Update
  • Delete
  • Approve
  • Archive

The platform avoids separate:

create
update
delete

permissions unless future business requirements demand them.

Scope​

Represents the data boundary associated with a permission.

Scopes answer:

On which data can the operation be performed?

Attributes​

ScopeId
Name
Description

Scope Types​

school​

Entire school access.

Example:

Principal
SchoolAdmin

assigned-sections​

Access limited to assigned sections.

Example:

Teacher

own-children​

Access limited to children associated with the parent.

Example:

Parent

self​

Access limited to own records.

Example:

Profile
Preferences

none​

No data-level filtering required.

Examples:

school.settings.manage

Role Permission​

Represents a Permission and Scope assignment to a Role.

Attributes​

RolePermissionId

RoleId
PermissionId
ScopeId

Examples​

Teacher:

students.read
assigned-sections

attendance.manage
assigned-sections

Parent:

students.read
own-children

attendance.read
own-children

fees.read
own-children

Principal:

students.read
school

attendance.manage
school

fees.manage
school

Authentication Architecture

Login Flow​

Authentication Flow​

User
    ↓
Login
    ↓
Keycloak
    ↓
JWT Issued
    ↓
API Requests

The JWT establishes identity.

The JWT does not determine authorization.

School Context Architecture

Concept​

A user may belong to multiple schools.

Example:

User

School A
School B
School C

The frontend maintains a single active school.

Active School

All requests operate in the active school context.

School Context Switching​

Users may switch schools during a session without re-authenticating.

Example:

School A
    ↓
Switch
    ↓
School B

School switching triggers:

  • Permission recalculation
  • Navigation rebuild
  • Query refresh
  • Data reload

JWT and School Context​

School Context is not stored in JWT.

Reason:

School Context

is user-selectable and may change during the session.

JWT contains identity.

The active school context is resolved separately.

Authorization Architecture

High-Level Flow​

Authorization Evaluation​

Request:

GET /students

Required Permission:

students.read

System:

Resolve Membership
Resolve Roles
Resolve Role Permissions
Find students.read
Resolve Scope
Apply Data Filters

If validation passes:

Access Granted

otherwise:

Access Denied

Scope Resolution

Authorization occurs in two phases.

Phase 1​

Permission Validation.

Example:

students.read

Phase 2​

Scope Resolution.

Example:

assigned-sections

becomes:

WHERE section_id IN (...)

The authorization layer converts business scopes into query filters.

Multi-Role Authorization

A user may possess multiple roles within the same membership.

Example:

Teacher
+
Parent

Permissions become the union of all role permissions.

For identical permissions, scopes are merged.

Example:

students.read
assigned-sections

students.read
own-children

Results include both:

Assigned Students
+
Own Children

Navigation Authorization

Navigation is permission-driven.

Navigation must never be role-driven.

Incorrect:

Teacher Menu
Parent Menu
Admin Menu

Correct:

Permissions
    ↓
Visible Navigation

Backend Design

Authorization Guard​

Every secured endpoint should declare required permissions.

Example:

students.read
students.manage
fees.manage

Responsibilities:

  • Validate JWT
  • Resolve membership
  • Resolve permission
  • Resolve scope
  • Grant or deny