UserMatrix — Modular Authentication Backend
A production-grade, modular auth backend: OTP two-factor login, granular RBAC, token rotation and waitlist management — built as a self-hostable foundation for SaaS platforms instead of another vendor-locked BaaS dependency.
- Role
- Backend Architecture
- Status
- Open Source
Architecture: UserMatrix — modular auth backend
UserMatrix is a modular authentication backend designed as a production-ready foundation for SaaS platforms and multi-tenant applications. It exists because most projects need the same hard parts — sessions, revocation, permissions, recovery — and usually rebuild them worse.
The system
The backend covers the full identity lifecycle:
- Onboarding — email/password registration, Google sign-in, email and phone verification, waitlist management for controlled launches.
- Authentication — password login plus TOTP-based second factor, single-use refresh tokens with rotation, global logout across all devices.
- Authorization — a role/permission matrix checked per request, not boolean admin flags.
- Account operations — password reset, profile updates, GDPR-compliant account deletion.
Engineering highlights
- Revocation without statefulness: access tokens stay stateless; revocation happens at the refresh boundary through a Redis blacklist whose entries expire exactly when the tokens they invalidate would.
- Permissions as data: the RBAC matrix lives in PostgreSQL, making permission changes auditable without deploys.
- Failure accounting: OTP attempts are counted per account in Redis with TTL windows, turning brute-force attempts into a rate-limiting problem rather than an incident.
- Clean seams: auth issues tokens and answers permission queries; business logic never touches session storage.
Result
UserMatrix runs as the reusable auth foundation for SaaS-shaped projects — self-hosted, containerized, with the security posture (rotation, rate limits, audit-friendly events) that enterprise environments expect.
architecture
Gateway (rate limiting, CORS, routing) → Auth Service (password/OTP verification, RBAC checks, session and token rotation) → PostgreSQL (users, roles, permissions, waitlist) + Redis (session blacklist, OTP attempt counters, rate-limit counters). The waitlist module hangs orthogonally off the user table.
select a node to inspect responsibility, I/O, failure modes & security
- ▸OTP-based two-factor authentication
- ▸RBAC with a granular role/permission matrix
- ▸Access/refresh token rotation
- ▸Waitlist & invite management for launches
- ▸Modular: each module usable and extendable independently
- ▸No vendor lock-in — must be self-hostable
- ▸Enterprise-grade security practice (tokens, rate limits)
- ▸Clean separation between auth and business logic
- ▸Stateless JWTs (scalable) vs. instant revocation (blacklist compromise)
- ▸Modularity vs. initial complexity: more parts, but each independently testable
- ▸TOTP two-factor; OTP attempt limits tracked in Redis
- ▸Token rotation: refresh tokens are single-use, old ones are revoked
- ▸Rate limiting per user/IP at the gateway; hardened CORS
- ▸No PII in cache; service accounts with minimal DB privileges
- ▸Redis as TTL layer: blacklist entries expire automatically
- ▸DB pooling and query limits against connection exhaustion
- ▸Integration tests: OTP flow, RBAC matrix, token rotation
- ▸Negative tests: expired tokens, exceeded OTP attempts
- ▸Containerized; gateway terminates TLS; configuration via env/secrets
- ▸Auth events (login, OTP failure, rotation) in structured logs — never secrets
- ▸Reusable auth backend for SaaS projects
- ▸Reference pattern for modular, security-first backend structure
- ▸Public repository: github.com/amariwan/UserMatrix
- ▸Case study documents OTP, RBAC, token rotation, Redis revocation and containerized deployment
- ▸Auth is a system, not a feature — design rotation and revocation from day one
- ▸Modularity pays off when modules own their tests and their secrets
problem
SaaS applications need an auth backend that goes beyond standard login — OTP, RBAC, token rotation, waitlist management — while staying secure, modular and extensible. Managed BaaS solutions create vendor lock-in and move user data flows into someone else's cloud.
context
UserMatrix was built as a robust, modular auth foundation for web applications and SaaS platforms. Instead of rebuilding an auth scaffold per project, it provides a tested base with the features modern apps actually need — deployable on your own infrastructure.
requirements
constraints
key decisions
Why: Stateless access tokens keep request handling fast while refresh-token rotation gives the system a revocation point.
Redis becomes part of the auth reliability path, but the token-theft window is materially reduced.
Why: TOTP is broadly supported by authenticator apps and avoids SMS as a weak recovery/authentication channel.
Users must manage an authenticator app; the system avoids telecom dependency and SIM-swap risk.
Why: Granular permission checks are auditable and testable; boolean admin flags collapse too many powers into one switch.
The permission model needs more schema and seed data, but authorization stays explicit as the product grows.