strat-gameplay-webapp/ACCESS_CONTROL.md

Discord User Access Control

Overview

The backend now includes Discord ID whitelist functionality to control who can access the system. This is useful for limiting access during testing/beta phases or for private leagues.

Configuration

Quick Start

Add this line to your backend/.env file:

# Allow specific Discord users (recommended)
ALLOWED_DISCORD_IDS=123456789012345678,987654321098765432

# OR allow everyone (not recommended for production)
ALLOWED_DISCORD_IDS=*

# OR leave empty to allow everyone (default, not recommended)
ALLOWED_DISCORD_IDS=

Finding Discord User IDs

Method 1: Enable Developer Mode in Discord

1. Open Discord Settings → Advanced
2. Enable "Developer Mode"
3. Right-click on a user → "Copy User ID"

Method 2: From OAuth Response

• Check backend logs after a user authenticates
• Look for: Discord ID {id} verified in whitelist

How It Works

Protection Points

The whitelist is checked at two authentication points:

1. Discord OAuth Flow (/api/auth/discord/callback)

   • After Discord authenticates the user
   • Before creating JWT token
   • Returns HTTP 403 if user not in whitelist

2. Test Token Endpoint (/api/auth/token)

   • Development/testing endpoint
   • Also checks whitelist
   • Returns HTTP 403 if Discord ID not allowed

Error Response

When access is denied, users see:

{
  "detail": "Access denied. Your Discord account is not authorized to access this system."
}

Usage Examples

Allow Only You and One Tester

# In backend/.env
ALLOWED_DISCORD_IDS=123456789012345678,987654321098765432

Allow Everyone (Development)

# Option 1: Use wildcard
ALLOWED_DISCORD_IDS=*

# Option 2: Leave empty
ALLOWED_DISCORD_IDS=

Production Recommendation

# Explicitly list all authorized users
ALLOWED_DISCORD_IDS=user1_id,user2_id,user3_id

Testing

Test With Authorized User

# 1. Add your Discord ID to .env
ALLOWED_DISCORD_IDS=your_discord_id

# 2. Restart backend
./stop-services.sh && ./start-services.sh

# 3. Try to authenticate - should succeed

Test With Unauthorized User

# 1. Set whitelist to specific IDs (not yours)
ALLOWED_DISCORD_IDS=123456789012345678

# 2. Restart backend
./stop-services.sh && ./start-services.sh

# 3. Try to authenticate - should get 403 error

Monitoring

Backend Logs

Whitelist checks are logged:

Allowed:

INFO - Discord ID 123456789012345678 verified in whitelist
INFO - User TestPlayer authenticated successfully

Denied:

WARNING - Discord ID 999999999999999999 not in whitelist - access denied

Whitelist Disabled:

WARNING - Discord whitelist disabled - allowing all users

Security Best Practices

1. ✅ DO use explicit user IDs in production
2. ✅ DO keep the whitelist in .env (gitignored)
3. ✅ DO restart backend after changing whitelist
4. ❌ DON'T use * or empty whitelist in production
5. ❌ DON'T commit Discord IDs to git
6. ❌ DON'T share your .env file

Troubleshooting

"Access denied" for authorized user

Check:

1. Discord ID is correct (no typos)
2. No extra spaces in .env
3. Backend has been restarted
4. Check backend logs for whitelist warnings

Fix:

# Verify your Discord ID
# Right-click your name in Discord → Copy User ID

# Update .env with correct ID
ALLOWED_DISCORD_IDS=your_correct_discord_id

# Restart
./stop-services.sh && ./start-services.sh

Everyone getting access when they shouldn't

Check:

1. ALLOWED_DISCORD_IDS is not *
2. ALLOWED_DISCORD_IDS is not empty
3. Backend logs show "verified in whitelist"

Fix:

# Set explicit whitelist
ALLOWED_DISCORD_IDS=your_id,friend_id

# Restart
./stop-services.sh && ./start-services.sh

Test tokens not working

Remember: Test token endpoint (/api/auth/token) also respects the whitelist!

# Your test token request must use an allowed Discord ID
{
  "user_id": "test-user-1",
  "username": "TestPlayer",
  "discord_id": "your_whitelisted_discord_id"  # Must be in whitelist!
}

Implementation Details

Code Locations

• Config: backend/app/config.py - Defines allowed_discord_ids setting
• Auth Routes: backend/app/api/routes/auth.py - Implements is_discord_id_allowed() check
• Discord OAuth: Line 198-203 - Checks whitelist after Discord auth
• Test Tokens: Line 376-380 - Checks whitelist for test tokens

Whitelist Format

• Comma-separated: id1,id2,id3
• Spaces ignored: id1, id2, id3 works too
• Empty/missing: Allows all users
• Wildcard: * allows all users

---

Created: 2025-01-25 Author: Jarvis Purpose: Control testing access via Discord user whitelist