Update documentation
This commit is contained in:
353
docs/design/authentication-system.md
Normal file
353
docs/design/authentication-system.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# Authentication System Design
|
||||
|
||||
## Overview
|
||||
|
||||
The Email Organizer implements a complete user authentication system using Flask-Login for session management and Werkzeug for password security. This document provides a detailed overview of the authentication architecture, components, and implementation details.
|
||||
|
||||
## System Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Authentication Flow"
|
||||
A[User Browser] --> B[Login Page]
|
||||
B --> C[Submit Credentials]
|
||||
C --> D[Validate Input]
|
||||
D --> E[Check Password Hash]
|
||||
E --> F[Create Session]
|
||||
F --> G[Redirect to Dashboard]
|
||||
end
|
||||
|
||||
subgraph "Backend Components"
|
||||
H[Auth Blueprint] --> I[Validation Logic]
|
||||
H --> J[Password Hashing]
|
||||
H --> K[Session Management]
|
||||
I --> L[User Model]
|
||||
J --> L
|
||||
K --> M[Flask-Login]
|
||||
end
|
||||
|
||||
subgraph "Security Measures"
|
||||
N[Password Validation] --> O[Complexity Requirements]
|
||||
N --> P[Hashing Algorithm]
|
||||
Q[Session Security] --> R[Cookie Protection]
|
||||
Q --> S[Timeout Handling]
|
||||
end
|
||||
|
||||
C --> D
|
||||
D --> I
|
||||
I --> J
|
||||
J --> K
|
||||
K --> F
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### 1. Auth Blueprint ([`app/auth.py`](app/auth.py:1))
|
||||
|
||||
The authentication blueprint handles all authentication-related routes and logic:
|
||||
|
||||
#### Routes
|
||||
- `/login`: GET/POST - User login page and authentication
|
||||
- `/signup`: GET/POST - User registration page and account creation
|
||||
- `/logout`: GET - User logout and session termination
|
||||
|
||||
#### Key Functions
|
||||
- `login()`: Handles user authentication
|
||||
- `signup()`: Manages user registration
|
||||
- `logout()`: Terminates user sessions
|
||||
- `validate_password()`: Enforces password complexity requirements
|
||||
|
||||
### 2. User Model ([`app/models.py`](app/models.py:13))
|
||||
|
||||
The User model extends Flask-Login's UserMixin to provide authentication functionality:
|
||||
|
||||
#### Authentication Methods
|
||||
- `set_password()`: Hashes and stores passwords
|
||||
- `check_password()`: Verifies password against hash
|
||||
|
||||
#### Security Attributes
|
||||
- Password hashing using Werkzeug's secure hashing algorithm
|
||||
- Email uniqueness constraint
|
||||
- Timestamp tracking for account management
|
||||
|
||||
### 3. Flask-Login Integration
|
||||
|
||||
The application uses Flask-Login for session management:
|
||||
|
||||
#### Configuration
|
||||
```python
|
||||
login_manager = LoginManager()
|
||||
login_manager.login_view = 'auth.login'
|
||||
login_manager.login_message = 'Please log in to access this page.'
|
||||
login_manager.login_message_category = 'warning'
|
||||
```
|
||||
|
||||
#### User Loader
|
||||
```python
|
||||
@login_manager.user_loader
|
||||
def load_user(user_id):
|
||||
return User.query.get(int(user_id))
|
||||
```
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
### User Registration
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User
|
||||
participant B as Browser
|
||||
participant A as Auth Blueprint
|
||||
participant DB as Database
|
||||
|
||||
U->>B: Navigate to /auth/signup
|
||||
B->>A: GET /auth/signup
|
||||
A->>B: Return signup form
|
||||
U->>B: Fill and submit form
|
||||
B->>A: POST /auth/signup
|
||||
|
||||
loop Validation
|
||||
A->>A: Validate input fields
|
||||
A->>A: Check email uniqueness
|
||||
A->>A: Validate password complexity
|
||||
end
|
||||
|
||||
A->>DB: Create new user record
|
||||
DB-->>A: User created
|
||||
A->>A: Hash and store password
|
||||
A->>B: Login user
|
||||
B->>U: Redirect to dashboard
|
||||
```
|
||||
|
||||
### User Login
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as User
|
||||
participant B as Browser
|
||||
participant A as Auth Blueprint
|
||||
participant DB as Database
|
||||
|
||||
U->>B: Navigate to /auth/login
|
||||
B->>A: GET /auth/login
|
||||
A->>B: Return login form
|
||||
U->>B: Submit credentials
|
||||
B->>A: POST /auth/login
|
||||
|
||||
A->>DB: Query user by email
|
||||
DB-->>A: User data
|
||||
|
||||
alt User exists
|
||||
A->>A: Verify password hash
|
||||
alt Password correct
|
||||
A->>A: Create session
|
||||
A->>B: Redirect to dashboard
|
||||
else Password incorrect
|
||||
A->>B: Show error message
|
||||
end
|
||||
else User not found
|
||||
A->>B: Show error message
|
||||
end
|
||||
```
|
||||
|
||||
### Password Validation
|
||||
|
||||
The system enforces strong password requirements:
|
||||
|
||||
```python
|
||||
def validate_password(password):
|
||||
"""Validate password strength."""
|
||||
if len(password) < 8:
|
||||
return False, "Password must be at least 8 characters long"
|
||||
if not re.search(r'[A-Z]', password):
|
||||
return False, "Password must contain at least one uppercase letter"
|
||||
if not re.search(r'[a-z]', password):
|
||||
return False, "Password must contain at least one lowercase letter"
|
||||
if not re.search(r'\d', password):
|
||||
return False, "Password must contain at least one digit"
|
||||
return True, "Password is valid"
|
||||
```
|
||||
|
||||
### Session Management
|
||||
|
||||
Flask-Login handles session security:
|
||||
|
||||
- **Session Cookies**: Secure, HttpOnly cookies for session storage
|
||||
- **CSRF Protection**: Built-in CSRF protection for form submissions
|
||||
- **Session Timeout**: Automatic session expiration
|
||||
- **Remember Me**: Optional persistent login functionality
|
||||
|
||||
## Security Measures
|
||||
|
||||
### 1. Password Security
|
||||
|
||||
#### Hashing Algorithm
|
||||
- Uses Werkzeug's `generate_password_hash()` and `check_password_hash()`
|
||||
- Implements PBKDF2 with SHA256 for secure password storage
|
||||
- Random salt generation for each password
|
||||
|
||||
#### Password Complexity
|
||||
- Minimum 8 characters
|
||||
- At least one uppercase letter
|
||||
- At least one lowercase letter
|
||||
- At least one digit
|
||||
- No maximum length limit
|
||||
|
||||
### 2. Input Validation
|
||||
|
||||
#### Client-Side Validation
|
||||
- HTML5 form validation
|
||||
- JavaScript feedback for user experience
|
||||
|
||||
#### Server-Side Validation
|
||||
- Comprehensive input sanitization
|
||||
- Email format validation
|
||||
- Length restrictions for all fields
|
||||
- SQL injection prevention through SQLAlchemy ORM
|
||||
|
||||
### 3. Session Security
|
||||
|
||||
#### Cookie Protection
|
||||
- Secure flag for HTTPS environments
|
||||
- HttpOnly flag to prevent JavaScript access
|
||||
- SameSite policy for cross-site request protection
|
||||
|
||||
#### Session Management
|
||||
- Automatic session regeneration on login
|
||||
- Session timeout handling
|
||||
- Logout cleanup
|
||||
|
||||
### 4. Error Handling
|
||||
|
||||
#### User-Friendly Messages
|
||||
- Clear validation error messages
|
||||
- General error messages for security-sensitive operations
|
||||
- No exposure of internal system details
|
||||
|
||||
#### Logging
|
||||
- Authentication attempt logging
|
||||
- Security event tracking
|
||||
- Error debugging information
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication Endpoints
|
||||
|
||||
| Endpoint | Method | Description | Authentication Required |
|
||||
|----------|--------|-------------|---------------------------|
|
||||
| `/auth/login` | GET/POST | User login | No |
|
||||
| `/auth/signup` | GET/POST | User registration | No |
|
||||
| `/auth/logout` | GET | User logout | Yes |
|
||||
|
||||
### Response Formats
|
||||
|
||||
#### Login Success
|
||||
```http
|
||||
HTTP/1.1 302 Found
|
||||
Location: /
|
||||
Set-Cookie: session=<session_id>; HttpOnly; Secure; Path=/
|
||||
```
|
||||
|
||||
#### Login Failure
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html
|
||||
|
||||
```
|
||||
|
||||
#### Registration Success
|
||||
```http
|
||||
HTTP/1.1 302 Found
|
||||
Location: /
|
||||
Set-Cookie: session=<session_id>; HttpOnly; Secure; Path=/
|
||||
```
|
||||
|
||||
#### Registration Failure
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html
|
||||
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default Value |
|
||||
|----------|-------------|--------------|
|
||||
| `SECRET_KEY` | Flask secret key for session encryption | `dev-secret-key` |
|
||||
|
||||
### Flask-Login Configuration
|
||||
|
||||
```python
|
||||
login_manager = LoginManager()
|
||||
login_manager.login_view = 'auth.login'
|
||||
login_manager.login_message = 'Please log in to access this page.'
|
||||
login_manager.login_message_category = 'warning'
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
|
||||
#### Authentication Tests
|
||||
- Test password validation logic
|
||||
- Test password hashing and verification
|
||||
- Test user creation and validation
|
||||
- Test session creation and management
|
||||
|
||||
#### Integration Tests
|
||||
- Test login flow with valid credentials
|
||||
- Test login flow with invalid credentials
|
||||
- Test registration flow with valid data
|
||||
- Test registration flow with invalid data
|
||||
- Test session persistence and timeout
|
||||
|
||||
### Security Tests
|
||||
|
||||
- Test SQL injection attempts
|
||||
- Test XSS vulnerabilities
|
||||
- Test session hijacking prevention
|
||||
- Test CSRF protection
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Database Optimization
|
||||
- Index on email column for fast login lookups
|
||||
- Efficient password hashing with proper salting
|
||||
- Session data stored in server-side session store
|
||||
|
||||
### Security vs. Usability Balance
|
||||
- Reasonable password complexity requirements
|
||||
- Clear error messages for failed login attempts
|
||||
- Session timeout balanced with user convenience
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Multi-Factor Authentication
|
||||
- SMS-based 2FA
|
||||
- TOTP (Time-based One-Time Password) support
|
||||
- Hardware token integration
|
||||
|
||||
### 2. OAuth Integration
|
||||
- Google OAuth
|
||||
- Facebook OAuth
|
||||
- GitHub OAuth
|
||||
|
||||
### 3. Password Reset
|
||||
- Email-based password reset
|
||||
- Secure token generation
|
||||
- Expiration handling
|
||||
|
||||
### 4. Account Management
|
||||
- User profile management
|
||||
- Email address changes
|
||||
- Password change functionality
|
||||
|
||||
### 5. Security Enhancements
|
||||
- Rate limiting for login attempts
|
||||
- Account lockout after failed attempts
|
||||
- Suspicious activity monitoring
|
||||
- IP-based security checks
|
||||
- Suspicious activity monitoring
|
||||
- IP-based security checks
|
||||
Reference in New Issue
Block a user