Authentication & Authorization
Auth strategy and RBAC decisions
Authentication & Authorization
Goal
Build a secure authentication system with SystemRole-based authorization using Auth.js database sessions.
Technology Decisions
| Component | Choice | Why |
|---|---|---|
| Auth Library | Auth.js (NextAuth) 5.x | Next.js integration, OAuth support |
| Session Strategy | Database sessions (MVP) | Simpler setup via PrismaAdapter |
| Authorization | SystemRole-based | SYSTEM_ADMIN, HR_ADMIN, MANAGER, EMPLOYEE |
| Future | JWT tokens | May add for API-to-API calls later |
MVP Session Strategy: Phase 01 uses database sessions via Auth.js PrismaAdapter (not JWT). The session callback enriches session with
tenantIdandsystemRole. See Phase 01 for implementation details.
Authentication
Login Methods (MVP)
- Google SSO (primary for MVP)
- Email/password (future enhancement)
Session Strategy (MVP)
- Database sessions via Auth.js PrismaAdapter
- Session stored in PostgreSQL
sessionstable - Session callback enriches with
tenantIdandsystemRole - Tenant auto-created on first login via
createUserevent
Session Contains
- User ID, email, name, image
tenantId(assigned by createUser event)systemRole(SYSTEM_ADMIN, HR_ADMIN, MANAGER, EMPLOYEE)
Authorization: SystemRole-Based Hierarchy
| Level | Identification | Access |
|---|---|---|
| System Admin | systemRole = SYSTEM_ADMIN | All tenants, system config |
| HR Admin | systemRole = HR_ADMIN | Full access within tenant |
| Manager | systemRole = MANAGER | Team management, approvals |
| Employee | systemRole = EMPLOYEE | Basic read, own record updates |
RBAC Permission Model
Permission Format
resource:action:scope
Components
| Component | Options |
|---|---|
| Resources | employees, time_off, documents, settings, users, roles |
| Actions | create, read, update, delete, approve |
| Scopes | own, team, department, all |
Examples
employees:read:all- Read all employees in tenantemployees:update:own- Update own employee recordtime_off:approve:department- Approve for department members
Wildcards
- Platform Admin:
*:*:*(all permissions) - Tenant Admin:
tenant:*:*(all within tenant)
Default Roles
| Role | Permissions |
|---|---|
| Admin | Full tenant access |
| Manager | Team management, approvals |
| Employee | Basic read, own record updates |
Security Rules
- Database sessions via Auth.js PrismaAdapter (MVP)
- TenantGuard validates tenant context on API requests
- SystemRoleGuard validates role permissions
- All endpoints protected by guards
- Audit logging for sensitive operations
See Phase 01 for implementation details