Authentication
Multi-strategy authentication system supporting local credentials, SSO, magic links, and 2FA.
Authentication Strategies
| Strategy | Flow | Backend Entry |
|---|---|---|
| Local (email/password) | JWT token pair (access + refresh) | backend/src/routes/auth.ts |
| Azure Entra ID SSO | OAuth2/OIDC redirect | backend/src/routes/entra-auth.ts |
| Magic Link | Email link with one-time token | backend/src/routes/auth.ts |
| Portal Token | Separate token-based auth for customers | backend/src/middleware/portal-auth.ts |
Password Security
- Hashed with argon2id via
Bun.password.hash()(no separate argon2 package) - Minimum 12 characters enforced
- Rate limited: 5 attempts per 15 minutes on auth endpoints
Optional TOTP 2FA
Users can enable time-based one-time passwords for second-factor authentication. Managed through the user settings interface.
Backend Sources
| File | Purpose |
|---|---|
backend/src/routes/auth.ts | Auth route handlers (login, signup, refresh, magic link) |
backend/src/services/auth-service.ts | Auth business logic |
backend/src/lib/auth.ts | Password hashing, token verification utilities |
backend/src/lib/tokens.ts | JWT creation and validation |
backend/src/middleware/auth.ts | JWT verification middleware for protected routes |
backend/src/routes/entra-auth.ts | Azure Entra ID SSO routes |
backend/src/services/entra/ | Entra ID service layer |
Frontend Pages
| Page | Purpose |
|---|---|
| Login | Email/password + SSO entry |
| Signup | New account registration |
| ForgotPassword | Password reset request |
| ResetPassword | Password reset with token |
| MagicLinkRequest | Request passwordless login link |
| MagicLinkVerify | Verify magic link token |
| PhoneNumberInput | Phone number entry for SMS auth |
| PhoneVerification | SMS code verification |
| AuthCallback | OAuth redirect handler |
State Management
Auth state is managed via a Zustand store at frontend/src/store/auth.ts. The store provides RBAC helpers like isTeamAdmin(), isTeamLead(), canCreateUsers(), and canDeactivateUsers().
Portal Authentication
The Portal uses a separate token-based authentication system (not session-based). Middleware at backend/src/middleware/portal-auth.ts validates portal tokens independently from the main auth flow.
Related
- Users — user accounts and profiles
- Portal — customer-facing portal with separate auth
- Azure Entra — SSO identity provider
- RBAC Authorization — role-based access control built on auth
- Middleware Stack — auth middleware ordering
- Backend Middleware — middleware implementation details
- Security Scanning — credential leak detection