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:

```bash
# 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:
```json
{
  "detail": "Access denied. Your Discord account is not authorized to access this system."
}
```

## Usage Examples

### Allow Only You and One Tester

```bash
# In backend/.env
ALLOWED_DISCORD_IDS=123456789012345678,987654321098765432
```

### Allow Everyone (Development)

```bash
# Option 1: Use wildcard
ALLOWED_DISCORD_IDS=*

# Option 2: Leave empty
ALLOWED_DISCORD_IDS=
```

### Production Recommendation

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

## Testing

### Test With Authorized User

```bash
# 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

```bash
# 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:**
```bash
# 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:**
```bash
# 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!

```bash
# 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