triviathang/AUTHELIA_SETUP.md

# Authelia OIDC Setup Guide

This guide will help you configure Authelia OIDC authentication for the Trivia Game application.

## Prerequisites

- An existing Authelia instance running and accessible
- Access to Authelia's configuration file (`configuration.yml`)
- Users and groups configured in Authelia

## Step 1: Configure Authelia Client

Add the following client configuration to your Authelia `configuration.yml`:

```yaml
identity_providers:
  oidc:
    clients:
      - id: trivia-app
        description: Trivia Game Application
        secret: <HASHED_SECRET>  # Generate using: authelia crypto hash generate --password 'your-secret-here'
        redirect_uris:
          - http://localhost:3000/auth/callback
          - http://localhost:5001/api/auth/callback
          # Add production URLs when deploying:
          # - https://trivia.example.com/auth/callback
          # - https://trivia-api.example.com/api/auth/callback
        scopes:
          - openid
          - email
          - profile
        grant_types:
          - authorization_code
          - refresh_token
        response_types:
          - code
        token_endpoint_auth_method: client_secret_basic
```

**Generate the hashed secret:**
```bash
authelia crypto hash generate --password 'your-random-secret-here'
```

Save the **plaintext secret** (not the hash) for the next step.

## Step 2: Configure Environment Variables

Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

Edit `.env` with your Authelia details:
```bash
# Replace with your actual Authelia URL
OIDC_ISSUER=https://auth.example.com

# Must match the client ID in Authelia config
OIDC_CLIENT_ID=trivia-app

# Use the PLAINTEXT secret (not the hashed one)
OIDC_CLIENT_SECRET=your-random-secret-here

# Adjust for production deployment
OIDC_REDIRECT_URI=http://localhost:5001/api/auth/callback
FRONTEND_URL=http://localhost:3000

# Set to 'true' in production with HTTPS
SESSION_COOKIE_SECURE=false
```

## Step 3: Restart Authelia

After updating Authelia's configuration:
```bash
# Restart Authelia to apply the new client configuration
systemctl restart authelia
# or
docker restart authelia
```

## Step 4: Start the Trivia Application

```bash
# Start with Docker Compose
docker compose up

# Or start backend and frontend separately
PORT=5001 uv run python main.py  # Backend
cd frontend/frontend && npm run dev  # Frontend
```

## Step 5: Test Authentication

1. Navigate to `http://localhost:3000`
2. You should be redirected to the login page
3. Click "Login with Authelia"
4. You'll be redirected to your Authelia instance
5. Log in with an Authelia user
6. After successful login, you'll be redirected back to the trivia app

**All authenticated users** can:
- Access all routes (question management, game setup, admin controls)
- Create/edit questions
- Start/control games
- View contestant screens

## Troubleshooting

### "OAuth authentication disabled" warning
- **Cause**: `OIDC_ISSUER` is not set
- **Solution**: Ensure your `.env` file exists and has `OIDC_ISSUER` configured

### "Invalid or expired token" errors
- **Cause**: JWT validation failing
- **Solutions**:
  - Verify `OIDC_ISSUER` matches exactly (no trailing slash)
  - Check Authelia logs for JWKS endpoint errors
  - Ensure clocks are synchronized between Authelia and trivia app

### Redirect loop on login
- **Cause**: Redirect URI mismatch
- **Solutions**:
  - Ensure `OIDC_REDIRECT_URI` matches one of the `redirect_uris` in Authelia config
  - Check that both frontend and backend URLs are correct

### WebSocket connection fails
- **Cause**: JWT token not being sent or invalid
- **Solutions**:
  - Check browser console for socket errors
  - Verify user is authenticated before joining game
  - Check backend logs for JWT validation errors

## Production Deployment

When deploying to production:

1. Update Authelia client redirect URIs:
```yaml
redirect_uris:
  - https://trivia.example.com/auth/callback
  - https://trivia-api.example.com/api/auth/callback
```

2. Update environment variables:
```bash
OIDC_ISSUER=https://auth.example.com
OIDC_REDIRECT_URI=https://trivia-api.example.com/api/auth/callback
FRONTEND_URL=https://trivia.example.com
SESSION_COOKIE_SECURE=true  # Important for HTTPS!
```

3. Ensure HTTPS is configured:
- Use a reverse proxy (nginx, Traefik, Caddy)
- Configure SSL certificates
- Update CORS origins to match production domains

## Security Best Practices

✅ **Do:**
- Use strong, random client secrets
- Enable `SESSION_COOKIE_SECURE=true` in production
- Use HTTPS for all production deployments
- Regularly rotate client secrets
- Monitor Authelia logs for suspicious activity

❌ **Don't:**
- Commit `.env` file to version control
- Use default secrets in production
- Disable HTTPS in production
- Share client secrets publicly

## Support

For Authelia-specific issues, refer to:
- [Authelia Documentation](https://www.authelia.com/docs/)
- [Authelia OIDC Configuration](https://www.authelia.com/configuration/identity-providers/oidc/)

For trivia app issues, check the backend logs:
```bash
docker compose logs backend -f
```