campaign_connector/docs/setup/authentication.md

Authentication Setup

This guide covers user authentication configuration for the web dashboard and API access.

Overview

SMS Campaign Manager supports two authentication methods:

• Session-based: Username/password login for web dashboard
• API key-based: Header authentication for scripts and automation

Both methods work simultaneously.

Web Dashboard Authentication

Configure Admin User

Add these lines to your .env file:

ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!

Restart the application:

docker compose restart

The admin user is created automatically on startup.

Login Process

1. Open http://localhost:5000/
2. You'll be redirected to /login
3. Enter your credentials
4. After login, sessions last 24 hours

Session Features

• 24-hour session duration
• HTTP-only cookies for security
• Automatic session cleanup
• Login tracking and auditing

API Key Authentication

API keys are used for programmatic access and automation scripts.

Key Types

Key	Variable	Purpose
Admin	ADMIN_API_KEY	Full access including database reset
User	USER_API_KEY	Standard operations
Termux	TERMUX_API_KEY	Android device communication

Usage

Include the key in request headers:

# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/endpoint

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/endpoint

User Roles

Admin Role

Full system access:

• All user permissions
• Create and delete users
• Database reset
• System configuration

User Role

Standard operations:

• Create and manage campaigns
• Send SMS messages
• Upload CSV files
• View analytics
• Change own password

Managing Users

Use the CLI tool to manage users:

python3 manage_users.py

Available options:

1. Create new user
2. List all users
3. Delete user
4. Change password

Create User via CLI

python3 manage_users.py
# Select option 1
# Enter username, password, role

Create User via API (Admin Only)

curl -X POST http://localhost:5000/api/admin/users/create \
  -H "Cookie: session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","password":"SecurePass123!","role":"user"}'

Testing Authentication

Test Web Login

# Should redirect to login
curl -i http://localhost:5000/

# Login via API
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword"}'

Test API Authentication

# Should fail (no key)
curl http://localhost:5000/api/campaign/list

# Should succeed
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list

Security Features

• PBKDF2 password hashing (100,000 iterations)
• HTTP-only session cookies
• Secure session tokens
• Constant-time password comparison
• Failed login tracking

Troubleshooting

Can't Log In

# Verify user exists
python3 manage_users.py
# Select option 2

# Reset password via .env
nano .env
# Update ADMIN_PASSWORD
docker compose restart

Session Expires Too Quickly

Session duration is configured in src/app.py. Default is 24 hours.

Forgot Password

# Via CLI
python3 manage_users.py
# Select option 4 (Change password)

# Or reset via .env
nano .env
# Update ADMIN_PASSWORD
docker compose restart

Related Documentation

• Installation Guide - Initial setup
• Security Setup - API key configuration
• User Management - Detailed user guide
• API Endpoints - Authentication endpoints