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:

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:

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:

cp .env.example .env

Edit .env with your Authelia details:

# 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:

# Restart Authelia to apply the new client configuration
systemctl restart authelia
# or
docker restart authelia

Step 4: Start the Trivia Application

# 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:

redirect_uris:
  - https://trivia.example.com/auth/callback
  - https://trivia-api.example.com/api/auth/callback

2. Update environment variables:

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
• Authelia OIDC Configuration

For trivia app issues, check the backend logs:

docker compose logs backend -f