Skip to content

ADR-0002. RBAC via Casbin + PolicyDefinition edge table

FieldValue
StatusAccepted
Date2026-02-04
Decidersidentity-team
Supersedes

Context

  • We need a flexible RBAC model that supports:
    • System fixed roles (SUPER_ADMIN, ADMIN, OPERATOR, OWNER, CASHIER, EMPLOYEE, CUSTOMER, GUEST)
    • Custom merchant roles
    • Permission grants (Role → Permission)
    • Scoping (User can be SCOPED_OWNER for organizer X but EMPLOYEE for organizer Y)
  • Two natural approaches:
    1. Triple tables: User_Role, Role_Permission, plus separate scoping
    2. Single edge table with subject + target polymorphism

Decision

Use a single PolicyDefinition table with two variants:

VariantSubjectTargetUse
GROUPUserRole / Organizer / Merchant"User X has role Y" or "User X belongs to merchant Z"
PERMISSIONRolePermission"Role Y has permission Z"

Plus a scope field (SYSTEM / ORGANIZER / MERCHANT) to constrain edges to a context.

Casbin's RBAC model is configured to evaluate this table at request time. Per-edge changes propagate immediately (no role-recompile step).

Consequences

ProsCons
Single table for all RBAC edges; uniform queryPolymorphic — no DB-level FK to subject/target
Scope field lets one user be different roles per organizerCasbin's evaluation cost grows with edge count
Custom merchant roles are first-class (not hard-coded)Permission-check latency requires Redis caching at sister side
Add new variants (e.g. RESOURCE for ABAC) without schema migrationAudit/diff of "who can do X" requires graph traversal

Alternatives Considered

OptionProsConsWhy rejected
Triple tables (UserRole, RolePermission)Clear semanticsTwo more migrations + parallel write pathsWorse maintenance
Single jsonb permission set per UserFast readNo history; no group inheritance; impossible to query "who has X"Wrong primitive
Spicedb / external authzIndustry standardOperational overhead; vendor latencyPremature for our scale

References

  • core/src/models/schemas/identity/policy-definition/schema.ts
  • services/policy-definition/ — 4 specialized writers
  • casbin model file (Casbin RBAC with domains)

Proprietary and Confidential. Unauthorized copying, distribution, or use of this software is strictly prohibited.