initial

2025-12-22 14:47:25 -05:00
parent d4e859f9a7
commit 00e9eb8986
81 changed files with 13933 additions and 0 deletions
--- a/AUTHELIA_SETUP.md
+++ b/AUTHELIA_SETUP.md
@@ -0,0 +1,183 @@
+# 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
+```