campaign_connector/docs/guides/user-management.md

User Management Guide - SMS Campaign Manager

🎉 No More ModHeader Required!

Your application now has a complete user management system with session-based authentication. Users can log in through a web interface and stay logged in without needing browser extensions or API keys in headers.

---

🏗️ System Architecture

Dual Authentication System

Your application now supports two types of authentication:

1. Session-Based Authentication (Web Dashboard)

   • Users log in with username/password
   • Sessions last 24 hours
   • Automatic login persistence
   • No browser extensions needed

2. API Key Authentication (Programmatic Access)

   • For external scripts and integrations
   • Uses X-API-Key header
   • Three roles: Admin, User, Termux

---

🚀 Quick Start

Step 1: Add Default Admin to .env

Edit your .env file and add:

# User Management
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!

Step 2: Restart Application

cd /mnt/storagessd1tb/campaign_connector
docker-compose restart

On first start, the system will automatically create the admin user from your .env file.

Step 3: Access the Login Page

Open your browser and go to:

http://localhost:5000/login

Or via Tailscale:

http://your-tailscale-ip:5000/login

Step 4: Log In

• Username: admin (or what you set in .env)
• Password: Your password from .env

You'll be redirected to the dashboard and stay logged in for 24 hours!

---

👥 Managing Users

Using the CLI Tool

The easiest way to manage users is with the command-line tool:

cd /mnt/storagessd1tb/campaign_connector
python3 manage_users.py

This provides an interactive menu:

📱 SMS Campaign Manager - User Management
══════════════════════════════════════════════════════════════════════

Choose an option:
  1. Create new user
  2. List all users
  3. Delete user
  4. Change password
  5. Exit

Choice [1-5]:

Creating Users via CLI

python3 manage_users.py
# Select option 1
# Follow prompts to create user

Example:

Username: john
Password: ********
Confirm password: ********

Select role:
  1. Admin (full access)
  2. User (regular access)
Choice [1-2]: 2

Email (optional): john@example.com
Full name (optional): John Doe

✅ User 'john' created successfully (role: user)

Creating Users via API (Admin Only)

curl -X POST http://localhost:5000/api/admin/users/create \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane",
    "password": "SecurePassword123!",
    "role": "user",
    "email": "jane@example.com",
    "full_name": "Jane Smith"
  }'

Listing Users

# Via CLI
python3 manage_users.py
# Select option 2

# Via API (admin only)
curl http://localhost:5000/api/admin/users \
  -H "Cookie: session=YOUR_SESSION_COOKIE"

Deleting Users

# Via CLI
python3 manage_users.py
# Select option 3

# Via API (admin only)
curl -X DELETE http://localhost:5000/api/admin/users/username \
  -H "Cookie: session=YOUR_SESSION_COOKIE"

Changing Passwords

# Via CLI
python3 manage_users.py
# Select option 4

# Via Web Dashboard
# User can change their own password through settings
curl -X POST http://localhost:5000/api/auth/change-password \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "OldPass123!",
    "new_password": "NewSecurePass456!"
  }'

---

🔐 User Roles

Admin Role

Full system access

Permissions:

• ✅ Everything User can do
• ✅ Create/delete other users
• ✅ View all users
• ✅ Database reset
• ✅ System configuration

Use cases:

• System administrators
• Primary account owners

User Role

Regular application access

Permissions:

• ✅ Create and manage campaigns
• ✅ Send SMS messages
• ✅ Upload CSV files
• ✅ View analytics
• ✅ Manage conversations
• ✅ Change own password
• ❌ Cannot create/delete users
• ❌ Cannot reset database

Use cases:

• Team members
• Campaign managers
• Regular users

---

🌐 How Login Works

Login Flow

1. User visits / (dashboard)

   • Not logged in → Redirected to /login
   • Logged in → Shows dashboard

2. User enters credentials

   • System checks username/password
   • Creates secure session token
   • Stores session in database
   • Sets HTTP-only session cookie

3. User accesses protected pages

   • Session cookie sent automatically
   • Server validates session token
   • User data available in request.current_user

4. Session expires after 24 hours

   • User must log in again
   • Old sessions automatically cleaned up

Security Features

✅ PBKDF2 password hashing - 100,000 iterations ✅ HTTP-only cookies - Prevents XSS attacks ✅ Session tokens - Cryptographically secure ✅ Constant-time comparison - Prevents timing attacks ✅ Session tracking - IP and user agent logging ✅ Failed login protection - Logged for monitoring

---

🔧 Configuration

Session Settings

Configured in src/app.py:

'SESSION_COOKIE_SECURE': False,  # Set to True for HTTPS
'SESSION_COOKIE_HTTPONLY': True,  # Prevent JavaScript access
'SESSION_COOKIE_SAMESITE': 'Lax',  # CSRF protection
'PERMANENT_SESSION_LIFETIME': 86400  # 24 hours

For production with HTTPS:

• Set SESSION_COOKIE_SECURE to True

Database Tables

User system creates two tables:

users table:

- id (primary key)
- username (unique)
- password_hash (PBKDF2)
- role (admin/user)
- created_at
- last_login
- is_active
- email
- full_name

user_sessions table:

- id (primary key)
- user_id (foreign key)
- session_token
- ip_address
- user_agent
- created_at
- expires_at
- is_active

---

🎨 Customizing the Login Page

The login page is at src/templates/login.html. You can customize:

• Logo/branding
• Colors (uses Tailwind CSS)
• Additional fields
• Links to help/support

Example customization:

<!-- Add company logo -->
<div class="text-center mb-8">
    <img src="/static/logo.png" alt="Company Logo" class="mx-auto mb-4">
    <h1 class="text-3xl font-bold text-gray-800">Your Company Name</h1>
</div>

---

📊 Monitoring and Auditing

Check Active Sessions

# In your application code
from core.user_auth import UserManager

user_manager = UserManager(config.DATABASE)
sessions = user_manager.list_active_sessions()  # Add this method if needed

View Login History

Check the user_sessions table:

docker-compose exec sms-campaign sqlite3 /app/data/campaign.db

SELECT u.username, s.created_at, s.ip_address, s.user_agent
FROM user_sessions s
JOIN users u ON s.user_id = u.id
ORDER BY s.created_at DESC
LIMIT 20;

Monitor Failed Logins

Check application logs:

docker-compose logs -f sms-campaign | grep "Failed login"

---

🔄 Migration from API Keys

If you were using ModHeader with API keys:

Before (with ModHeader):

1. Install ModHeader
2. Add X-API-Key header
3. Set value to API key
4. Access dashboard

After (with User Login):

1. Go to /login
2. Enter username/password
3. Click Sign In
4. Access dashboard (stays logged in)

API keys still work for:

• External scripts
• Automation
• Mobile apps
• Third-party integrations

---

🛡️ Security Best Practices

Password Requirements

Enforced by the system:

• Minimum 8 characters
• Recommended: Mix of letters, numbers, symbols

Recommendations

1. Use strong passwords

   • 12+ characters
   • Mix uppercase, lowercase, numbers, symbols
   • Use password manager

2. Rotate admin credentials

   • Change admin password every 90 days
   • Update .env file after changing

3. Monitor access

   • Review login logs regularly
   • Check for suspicious IPs
   • Disable inactive users

4. Limit admin accounts

   • Only create admin users when necessary
   • Most users should have 'user' role

5. Use HTTPS in production

   • Tailscale provides this automatically
   • Or set up reverse proxy with SSL

---

🐛 Troubleshooting

Can't Log In

Issue: Invalid username or password

Solutions:

1. Verify username is correct (case-sensitive)
2. Reset password via CLI:

   python3 manage_users.py
   # Choose option 4 (Change password)
   

3. Check if user exists:

   python3 manage_users.py
   # Choose option 2 (List users)
   

Session Expires Too Quickly

Issue: Getting logged out frequently

Solution: Increase session lifetime in src/app.py:

'PERMANENT_SESSION_LIFETIME': 604800  # 7 days instead of 24 hours

Database Locked Error

Issue: "database is locked" when creating users

Solution:

# Stop application
docker-compose down

# Start again
docker-compose up -d

# Try creating user again
python3 manage_users.py

Forgot Admin Password

Solution 1: Reset via .env

# Edit .env
ADMIN_PASSWORD=NewSecurePassword789!

# Restart application
docker-compose restart

# System will update the password

Solution 2: Create new admin via Docker

docker-compose exec sms-campaign python3 manage_users.py

Login Page Not Showing

Issue: Redirects not working

Solutions:

1. Clear browser cache
2. Check if logged in: http://localhost:5000/api/auth/status
3. Logout manually: http://localhost:5000/api/auth/logout

---

📱 Mobile/Remote Access

Access via Tailscale

Your application is accessible via Tailscale VPN:

https://your-tailscale-hostname:5000/login

Remember Me Feature

The "Remember me" checkbox (currently cosmetic) can be enhanced to extend session duration for trusted devices.

---

🔌 API Endpoints

Public Endpoints (No Auth Required)

• GET /login - Login page
• POST /api/auth/login - Login handler
• GET /health - Health check

User Endpoints (Login Required)

• GET / - Dashboard
• GET /api/auth/status - Check login status
• POST /api/auth/logout - Logout
• POST /api/auth/change-password - Change password

Admin Endpoints (Admin Role Required)

• GET /api/admin/users - List users
• POST /api/admin/users/create - Create user
• DELETE /api/admin/users/<username> - Delete user

---

🎯 Next Steps

Recommended Setup

1. Create initial admin:

   # Add to .env
   ADMIN_USERNAME=your_username
   ADMIN_PASSWORD=SecurePassword123!
   
   # Restart
   docker-compose restart
   

2. Log in and test:

   • Visit http://localhost:5000/login
   • Log in with credentials
   • Access dashboard

3. Create additional users:

   python3 manage_users.py
   

4. Remove .env credentials (optional for security):

   • After creating admin via database
   • Remove ADMIN_USERNAME and ADMIN_PASSWORD from .env
   • Users only in database (more secure)

5. Set up monitoring:

   • Monitor logs for failed logins
   • Review user list periodically
   • Disable inactive users

Related Documentation

• Authentication Setup - Login configuration
• API Security - API key authentication
• Security Setup - Security configuration
• Quick Start - Getting started