User Access & Security
Module Code: AUTH Priority: P0 (Critical Foundation) Status: New (To be developed) Dependencies: None (Foundation module)
Related Documentation
- 🏠 Documentation Home - System overview & all modules
Overview
Purpose: Secure user authentication and session management providing the foundation for all system access and security controls.
Integration Points: All modules (every module requires authentication)
Functional Specifications
0.1 User Authentication
Login Methods:
| Method | Description | Priority |
|---|---|---|
| Username/Password | Standard credential-based login | P0 |
| Email/Password | Email as username alternative | P0 |
| Single Sign-On (SSO) | Corporate SSO integration (SAML/OAuth) | P1 |
| Multi-Factor Authentication (MFA) | SMS/Email/Authenticator app verification | P1 |
| Biometric | Fingerprint/Face recognition for mobile | P2 |
Login Process:
| Step | Action | Validation |
|---|---|---|
| 1 | User enters credentials | Format validation |
| 2 | System validates credentials | Database lookup, password hash comparison |
| 3 | Check account status | Active/Inactive/Locked/Suspended |
| 4 | Check password expiry | Force change if expired (90 days) |
| 5 | Verify IP whitelist (optional) | Corporate network restrictions |
| 6 | MFA challenge (if enabled) | SMS/Email/App verification code |
| 7 | Create session token | JWT or session ID generation |
| 8 | Log login event | Audit trail (timestamp, IP, device) |
| 9 | Redirect to dashboard | Based on user role |
Login Security:
| Feature | Description | Configuration |
|---|---|---|
| Password Complexity | Minimum 8 chars, uppercase, lowercase, number, special char | Configurable |
| Failed Login Attempts | Lock account after 5 failed attempts within 15 minutes | Configurable |
| Account Lockout Duration | 30 minutes auto-unlock or admin manual unlock | Configurable |
| Session Timeout | Idle timeout: 30 minutes, Absolute timeout: 8 hours | Configurable |
| Concurrent Sessions | Allow/Deny multiple simultaneous sessions per user | Configurable |
| IP Restrictions | Whitelist specific IP ranges for access | Optional |
| Device Fingerprinting | Track and alert on new device logins | Optional |
0.2 Session Management
Session Creation:
| Attribute | Description |
|---|---|
| Session ID | Unique cryptographically secure random token |
| User ID | Reference to authenticated user |
| Employee ID | Reference to employee record (if applicable) |
| Role IDs | List of active roles for this session |
| Permissions | Cached permission set for performance |
| Created At | Session creation timestamp |
| Last Activity | Last request timestamp for idle timeout |
| Expires At | Absolute expiration timestamp |
| IP Address | Client IP address |
| User Agent | Browser/device information |
| Location Info | Branch/Location context |
Session Operations:
| Operation | Description | Trigger |
|---|---|---|
| Create | Generate new session on successful login | Login success |
| Validate | Check session validity on each request | Every API call |
| Refresh | Extend session timeout on activity | User activity |
| Terminate | Destroy session and clear tokens | Logout, timeout, admin force |
| List Active | View all active sessions for user | User profile |
| Revoke All | Terminate all sessions for security | Password change, security breach |
0.3 Password Management
Password Rules:
| Rule | Requirement |
|---|---|
| Minimum Length | 8 characters |
| Complexity | At least 3 of: uppercase, lowercase, number, special character |
| History Check | Cannot reuse last 5 passwords |
| Dictionary Check | Reject common/weak passwords |
| Personal Info | Cannot contain username, email, name |
| Expiry | Force change every 90 days (configurable) |
| Initial Password | Temporary password sent via email, must change on first login |
Password Reset (Self-Service):
| Step | Action |
|---|---|
| 1 | User clicks “Forgot Password” |
| 2 | Enter email or username |
| 3 | System sends reset link to registered email |
| 4 | Link valid for 1 hour |
| 5 | User clicks link, redirected to reset page |
| 6 | Enter new password (with complexity validation) |
| 7 | Confirm new password |
| 8 | System invalidates old password and all sessions |
| 9 | Confirmation email sent |
| 10 | User logs in with new password |
0.4 Multi-Factor Authentication (MFA)
MFA Methods:
| Method | Description | Delivery |
|---|---|---|
| SMS OTP | 6-digit code via SMS | Mobile phone |
| Email OTP | 6-digit code via email | Email address |
| Authenticator App | TOTP (Time-based OTP) | Google Authenticator, Microsoft Authenticator |
| Backup Codes | 10 one-time use codes | Generated at setup |
0.5 Security Features
Security Measures:
| Feature | Description | Priority |
|---|---|---|
| Brute Force Protection | Rate limiting, account lockout | P0 |
| CSRF Protection | Token-based CSRF validation | P0 |
| XSS Prevention | Input sanitization, output encoding | P0 |
| SQL Injection Prevention | Parameterized queries, ORM | P0 |
| HTTPS Enforcement | Force SSL/TLS for all connections | P0 |
| Security Headers | HSTS, CSP, X-Content-Type-Options | P0 |
Data Model
User Authentication Table:
| Field | Type | Description |
|---|---|---|
| user_id | UUID | Primary key |
| username | VARCHAR(50) | Unique username |
| VARCHAR(255) | Unique email | |
| password_hash | VARCHAR(255) | Hashed password |
| password_salt | VARCHAR(255) | Password salt |
| password_changed_at | TIMESTAMP | Last password change |
| mfa_enabled | BOOLEAN | MFA status |
| account_status | ENUM | Active/Inactive/Locked/Suspended |
| failed_login_attempts | INT | Current failed attempt count |
| locked_until | TIMESTAMP | Account unlock time |
| last_login_at | TIMESTAMP | Last successful login |
| created_at | TIMESTAMP | Account creation |
Session Table:
| Field | Type | Description |
|---|---|---|
| session_id | UUID | Primary key |
| user_id | UUID | Foreign key to user |
| token | VARCHAR(512) | Session token (encrypted) |
| created_at | TIMESTAMP | Session start |
| last_activity_at | TIMESTAMP | Last request |
| expires_at | TIMESTAMP | Absolute expiration |
| ip_address | VARCHAR(45) | Client IP |
| is_active | BOOLEAN | Session status |
Business Rules
| Rule | Description |
|---|---|
| Unique Username | Username must be unique across system |
| Unique Email | Email must be unique across system |
| Active Account Only | Only active accounts can log in |
| Session Limit | Maximum 5 concurrent sessions per user |
| HTTPS Only | No plain HTTP allowed in production |
Integration Points
Outbound:
- M01: Role & Permission Management (check permissions)
- M02: Employee Management (link to employee)
- All modules (validate session)
Inbound:
- Corporate Identity Provider (SSO)
- Email System (password reset)
- SMS Gateway (MFA codes)
Key Performance Indicators
| Metric | Target |
|---|---|
| Login Time | < 2 seconds |
| Session Validation | < 50ms |
| Login Success Rate | > 95% |
| MFA Adoption | > 80% |
| Security Incidents | 0 |
Last Updated: November 14, 2025 Version: 1.0