Skip to main content

ADR-006: Use Keycloak for Identity and Access Management

Status​

Accepted

Date​

2026-07-22

Context​

Chilarai requires a centralized solution for:

  • Authentication
  • Authorization
  • Single Sign-On
  • User Federation
  • Password Management
  • Multi-Factor Authentication
  • Session Management

The platform supports multiple user types:

  • Platform Administrators
  • School Administrators
  • Teachers
  • Staff
  • Parents

The platform also supports:

  • Multi-school memberships
  • Multi-role users
  • Future parent self-service
  • Future student self-service
  • Future mobile applications

An identity and access management solution is required before backend implementation begins.

Decision Drivers​

The selected solution should:

  • Support OpenID Connect (OIDC)
  • Support OAuth2
  • Be self-hostable
  • Support Multi-Factor Authentication
  • Support Single Sign-On
  • Support Identity Federation
  • Support User Management APIs
  • Integrate easily with NestJS
  • Integrate easily with Next.js
  • Work for multi-tenant SaaS scenarios
  • Avoid building custom authentication infrastructure

Alternatives Considered​

Option 1: Build Custom Authentication​

Build authentication and authorization directly within Chilarai.

Examples:

  • User Password Storage
  • Login APIs
  • Password Reset
  • MFA
  • Session Management

Advantages​

  • Complete control
  • No external dependency

Disadvantages​

  • Significant engineering effort
  • Security risk
  • Ongoing maintenance burden
  • MFA implementation complexity
  • Password management complexity
  • Audit and compliance challenges

Assessment​

Authentication is not a problem Chilarai should solve.

Building custom authentication provides little business value and introduces significant security risk.

Option 2: Managed Identity Provider​

Examples:

  • Auth0
  • Azure AD B2C
  • Clerk

Advantages​

  • Reduced operational overhead
  • Rich feature set
  • Fast setup

Disadvantages​

  • Vendor lock-in
  • Ongoing subscription costs
  • Less deployment flexibility
  • Reduced customization opportunities

Assessment​

A managed service may be appropriate in the future, but introduces recurring costs and external dependencies.

Option 3: Keycloak​

Use Keycloak as the centralized identity provider.

Advantages​

  • Open source
  • Self-hosted
  • OIDC compliant
  • OAuth2 compliant
  • MFA support
  • Social login support
  • Identity federation support
  • User management APIs
  • Proven enterprise platform
  • Strong community support

Disadvantages​

  • Additional component to operate
  • Requires configuration and upgrades
  • Learning curve for administrators

Assessment​

Keycloak provides the required capabilities while maintaining platform ownership and deployment flexibility.

Decision​

Use Keycloak as the Identity and Access Management platform for Chilarai.

Keycloak will be responsible for authentication and identity management.

Chilarai will remain responsible for user lifecycle management, memberships, roles, and business authorization.

Identity Ownership Model​

Authentication and business identity are intentionally separated.

Keycloak Responsibilities​

Keycloak owns:

  • Authentication
  • Passwords
  • MFA
  • Session Management
  • Login Flows
  • Identity Federation
  • Token Issuance

Chilarai Responsibilities​

Chilarai owns:

  • User Profiles
  • School Memberships
  • Roles
  • Parent Approvals
  • Staff Records
  • Business Authorization

User Mapping​

A Chilarai User has a one-to-one relationship with a Keycloak User.

Relationship:

Keycloak User
       ↓
ExternalIdentityId
       ↓
Chilarai User

The Keycloak user identifier is stored in:

ExternalIdentityId

within the User domain.

Registration Model​

Parent Registration​

Parents may self-register.

Flow:

Parent
    ↓
Create Account
    ↓
Keycloak User
    ↓
Chilarai User
    ↓
Pending School Membership

Staff Onboarding​

Staff accounts are created through Chilarai administration screens.

Flow:

School Admin
    ↓
Create User
    ↓
Keycloak Admin API
    ↓
Keycloak User Created
    ↓
School Membership Created

School Administrator Onboarding​

Initial School Administrators are created during school onboarding.

Identity Resolution​

Before creating a new Keycloak user:

  1. Check Email
  2. Check Mobile Number

If a matching identity exists:

  • Reuse the identity
  • Create School Membership
  • Assign Roles

If no identity exists:

  • Create Keycloak User
  • Create Chilarai User

This prevents duplicate identities.

Administrative Ownership​

Administrative users never interact directly with Keycloak.

All identity operations occur through Chilarai administrative interfaces.

Examples:

  • Create User
  • Approve Parent
  • Assign Roles
  • Suspend User

Chilarai uses Keycloak Admin APIs behind the scenes.

Authorization Model​

Authentication is performed by Keycloak.

Authorization is performed by Chilarai.

Authorization is derived from:

User
    ↓
School Membership
    ↓
Roles

Examples:

  • School Admin
  • Teacher
  • Parent
  • Principal
  • Accountant

Roles are not managed directly in Keycloak.

Business roles belong to Chilarai.

Architectural Rules​

Keycloak is an Infrastructure Component​

Keycloak should be treated as infrastructure.

Business logic must not be implemented in Keycloak.

Chilarai is the System of Record​

Business identity data belongs to Chilarai.

Examples:

  • Memberships
  • Role Assignments
  • Parent Relationships
  • Staff Records

No Direct Keycloak Administration​

Operational users should never be required to access Keycloak administration screens.

Consequences​

Positive Consequences​

  • Proven authentication platform
  • Reduced security risk
  • Faster development
  • MFA support
  • SSO support
  • Future social login support
  • Clear separation of responsibilities

Negative Consequences​

  • Additional service to operate
  • Additional deployment component
  • Team must understand Keycloak administration

Future Evolution​

The chosen architecture supports future capabilities including:

  • Social Login
  • Student Login
  • Mobile Authentication
  • Identity Federation
  • Enterprise SSO
  • Multi-Factor Authentication Expansion

These capabilities should not require redesign of the User domain.

Follow-up Actions​

  • Implement Keycloak integration.
  • Define authentication flows.
  • Define token handling.
  • Define authorization middleware.
  • Define user provisioning workflows.
  • ADR-001: Use Nx Monorepo
  • ADR-002: Use Next.js
  • ADR-003: Use NestJS
  • ADR-004: Use PostgreSQL
  • ADR-005: Use Zod
  • ADR-007: Use Modular Monolith

Summary​

Core decisions:

  • Keycloak is the Identity Provider.
  • Keycloak owns authentication.
  • Chilarai owns business authorization.
  • Chilarai User maps one-to-one with a Keycloak User.
  • Parent self-registration is supported.
  • Staff onboarding is managed through Chilarai.
  • Identity resolution occurs before user creation.
  • Administrative users never interact directly with Keycloak.
  • Business roles are managed by Chilarai, not Keycloak.