Dashboard Authentication Guide¶

Complete guide to setting up authentication for the RustSocks dashboard with optional Altcha CAPTCHA.

Table of Contents¶

Quick Start
Configuration
Altcha CAPTCHA
Security Best Practices
Troubleshooting

Quick Start¶

Basic Authentication (Username/Password Only)¶

Enable authentication in config:

[sessions]
enabled = true
stats_api_enabled = true
dashboard_enabled = true

[sessions.dashboard_auth]
enabled = true
altcha_enabled = true
session_secret = "your-super-secret-random-string-here"
session_duration_hours = 24

[[sessions.dashboard_auth.users]]
username = "admin"
password = "SecurePassword123"

Start the server:

./target/release/rustsocks --config config/rustsocks.toml

Access dashboard: Navigate to http://127.0.0.1:9090
Login with credentials from config

Configuration¶

Session Settings¶

[sessions.dashboard_auth]
# Enable/disable authentication
enabled = true

# Session secret for token generation
# CRITICAL: Use a long, random string in production
# Generate with: openssl rand -base64 32
session_secret = "change-me-to-very-long-random-secret-string"

# How long sessions remain valid (in hours)
session_duration_hours = 24  # Default: 24 hours

# Mark cookies as Secure when serving the dashboard over HTTPS
cookie_secure = true

User Management¶

Add multiple users with different credentials:

[[sessions.dashboard_auth.users]]
username = "admin"
password = "AdminPassword123"

[[sessions.dashboard_auth.users]]
username = "monitor"
password = "MonitorPassword456"

[[sessions.dashboard_auth.users]]
username = "operator"
password = "OperatorPassword789"

Note: Password hashes in PHC format are supported today. If the password field starts with $argon2, RustSocks will verify the hash using Argon2. Plaintext passwords are still accepted for local testing, but production deployments should use hashed credentials.

Base Path Support¶

Dashboard authentication respects base path configuration:

[sessions]
base_path = "/rustsocks"

All auth endpoints will be accessible at: - /rustsocks/api/auth/login - /rustsocks/api/auth/logout - /rustsocks/api/auth/check

Altcha CAPTCHA¶

Altcha is a self-hosted, privacy-first proof-of-work CAPTCHA that works completely offline without external services.

How Altcha Works¶

Server generates a cryptographic challenge (HMAC-SHA256 signed hash)
Browser solves proof-of-work puzzle by finding a secret number
Server verifies the solution before allowing login

Features¶

✅ Fully self-hosted - No external dependencies ✅ Privacy-first - No tracking, no third-party services ✅ Offline-capable - Works without internet ✅ Open source - Based on Altcha ✅ HMAC-secured - Cryptographically signed challenges ✅ Configurable difficulty - Adjust PoW complexity

Enabling Altcha¶

1. Update configuration:

[sessions.dashboard_auth]
enabled = true
altcha_enabled = true  # Enable Altcha CAPTCHA
session_secret = "your-secret-key-used-for-hmac-signing"

2. Rebuild dashboard (if modified):

cd dashboard
npm run build
cd ..

3. Restart server:

./target/release/rustsocks --config config/rustsocks.toml

4. Test login page: - Navigate to dashboard - You'll see Altcha widget on login page - Widget will solve PoW challenge automatically - Submit form after challenge is solved

Built-in vs External Altcha¶

Built-in Endpoint (Default)¶

When altcha_enabled = true with no altcha_challenge_url:

[sessions.dashboard_auth]
altcha_enabled = true
# No altcha_challenge_url specified - uses built-in

Endpoint: GET /api/auth/altcha-challenge

Response format:

{
  "algorithm": "SHA-256",
  "challenge": "hex_hash_of_salt",
  "salt": "random_string?expires=timestamp",
  "signature": "hmac_sha256_signature",
  "maxnumber": 50000
}

Parameters: - algorithm: Hash algorithm (SHA-256) - challenge: SHA-256 hash of salt - salt: Random salt with expiration (20 minutes) - signature: HMAC-SHA256(challenge, secret_key) - maxnumber: Proof-of-work difficulty (0-50000)

External Altcha API (Optional)¶

Use hosted Altcha service:

[sessions.dashboard_auth]
altcha_enabled = true
altcha_challenge_url = "https://eu.altcha.org/api/v1/challenge?apiKey=YOUR_KEY"

Or self-host Altcha server:

altcha_challenge_url = "http://your-altcha-server.com/api/challenge"

Difficulty Configuration¶

Adjust maxnumber in src/api/auth.rs:

maxnumber: Some(50000),  // Difficulty: 0-50000

Recommended values: - 10000 - Easy (fast, less security) - 50000 - Medium (default, balanced) - 100000 - Hard (slow, more security) - 250000 - Very hard (very slow, maximum security)

Note: Higher values increase solve time but provide stronger bot protection.

Security Best Practices¶

1. Session Secret¶

❌ Bad:

session_secret = "secret123"

✅ Good:

session_secret = "j8Kx9m2Nq5Pv7Yt3Zw1Bc4Df6Gh8Jl0Mn2Op4Qr6St8Uv0Wx2Yz4Ab6Cd8Ef0"

Generate secure secret:

openssl rand -base64 48

2. Strong Passwords¶

Minimum requirements: - 12+ characters - Mix of uppercase, lowercase, numbers, symbols - No dictionary words - Unique per user

3. HTTPS in Production¶

Always use HTTPS when deploying dashboard:

[server.tls]
enabled = true
certificate_path = "/path/to/cert.pem"
private_key_path = "/path/to/key.pem"

4. Protect API Endpoints¶

If the API is exposed, set a token to require auth on /api/*:

[sessions]
api_token = "change-me"

Requests can authenticate via Authorization: Bearer <token> or x-api-token.

5. Session Duration¶

Adjust based on security needs:

session_duration_hours = 8  # Work day
# session_duration_hours = 1  # High security
# session_duration_hours = 168  # 1 week (convenience)

6. Firewall Protection¶

Restrict dashboard access:

# Allow only from specific IP
iptables -A INPUT -p tcp -s 192.168.1.0/24 --dport 9090 -j ACCEPT
iptables -A INPUT -p tcp --dport 9090 -j DROP

Or use reverse proxy (nginx/Apache) with IP whitelist.

Troubleshooting¶

Symptoms: Browser shows basic auth popup instead of login page

Solution: Check config:

[sessions.dashboard_auth]
enabled = true  # Must be true

Rebuild dashboard if modified:

cd dashboard && npm run build

Check browser console for errors

Common issues:

JavaScript disabled - Enable JavaScript
HTTPS required - Altcha uses Web Crypto API (requires secure context)
Old browser - Use modern browser with Web Components support

Test Altcha endpoint:

curl http://127.0.0.1:9090/api/auth/altcha-challenge

Should return JSON challenge.

Session Expires Immediately¶

Check: 1. System clock - ensure server time is correct 2. Session secret - verify it's set correctly 3. Cookie settings - check browser accepts cookies

Debug:

# Check server logs for session creation
grep "User logged in" /var/log/rustsocks.log

Base Path Issues¶

Symptoms: Login works at root but not at /rustsocks

Solution: Verify base path consistency:

[sessions]
base_path = "/rustsocks"  # Must match deployment

Rebuild dashboard:

cd dashboard && npm run build

"Invalid credentials" Error¶

Check: 1. Username/password in config match exactly (case-sensitive) 2. No extra spaces in config 3. TOML syntax is correct

Test credentials:

# Print configured users (excluding passwords)
grep -A1 'dashboard_auth.users' config/rustsocks.toml

API Endpoints¶

POST /api/auth/login¶

Login with credentials.

Request:

{
  "username": "admin",
  "password": "password123",
  "altcha": "optional_altcha_payload"
}

Response (success):

{
  "success": true,
  "message": "Login successful",
  "username": "admin"
}

Sets cookie: rustsocks_session=<token>; HttpOnly; SameSite=Strict

POST /api/auth/logout¶

Logout and destroy session.

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

GET /api/auth/check¶

Check if current session is valid.

Response (authenticated):

{
  "authenticated": true,
  "username": "admin"
}

Response (not authenticated):

{
  "authenticated": false
}

GET /api/auth/altcha-config¶

Get Altcha configuration.

Response:

{
  "enabled": true,
  "challenge_url": null
}

GET /api/auth/altcha-challenge¶

Generate Altcha challenge (when enabled).

Response:

{
  "algorithm": "SHA-256",
  "challenge": "a1b2c3...",
  "salt": "xyz123?expires=1234567890",
  "signature": "9f8e7d...",
  "maxnumber": 50000
}

Example Configurations¶

Simple Auth (No CAPTCHA)¶

[sessions]
enabled = true
dashboard_enabled = true

[sessions.dashboard_auth]
enabled = true
altcha_enabled = false
session_secret = "your-secret-here"

[[sessions.dashboard_auth.users]]
username = "admin"
password = "AdminPass123"

With Altcha (Self-Hosted)¶

[sessions]
enabled = true
dashboard_enabled = true

[sessions.dashboard_auth]
enabled = true
altcha_enabled = true  # Enable CAPTCHA
session_secret = "your-secret-for-hmac-signing"

[[sessions.dashboard_auth.users]]
username = "admin"
password = "AdminPass123"

With Base Path¶

[sessions]
enabled = true
dashboard_enabled = true
base_path = "/socks"  # Dashboard at /socks

[sessions.dashboard_auth]
enabled = true
session_secret = "your-secret-here"

[[sessions.dashboard_auth.users]]
username = "admin"
password = "AdminPass123"

Access at: http://127.0.0.1:9090/socks

Future Enhancements¶

Planned features for future versions:

[ ] Password hashing (bcrypt/argon2)
[ ] Two-factor authentication (TOTP)
[ ] Role-based access control (RBAC)
[ ] LDAP/Active Directory integration
[ ] API key authentication
[ ] Audit logging
[ ] Brute-force protection
[ ] Session management UI

Need help? Check Project README or open an issue on GitHub.

Dashboard Authentication Guide¶

Table of Contents¶

Quick Start¶

Basic Authentication (Username/Password Only)¶

Configuration¶

Session Settings¶

User Management¶

Base Path Support¶

Altcha CAPTCHA¶

How Altcha Works¶

Features¶

Enabling Altcha¶

Built-in vs External Altcha¶

Built-in Endpoint (Default)¶

External Altcha API (Optional)¶

Difficulty Configuration¶

Security Best Practices¶

1. Session Secret¶

2. Strong Passwords¶

3. HTTPS in Production¶

4. Protect API Endpoints¶

5. Session Duration¶

6. Firewall Protection¶

Troubleshooting¶

Login Page Not Showing¶

Altcha Widget Not Loading¶

Session Expires Immediately¶

Base Path Issues¶

"Invalid credentials" Error¶

API Endpoints¶

POST /api/auth/login¶

POST /api/auth/logout¶

GET /api/auth/check¶

GET /api/auth/altcha-config¶

GET /api/auth/altcha-challenge¶

Example Configurations¶

Simple Auth (No CAPTCHA)¶

With Altcha (Self-Hosted)¶

With Base Path¶

Future Enhancements¶