launchpad-gateway/authelia/README.md

Authelia Setup Guide

This guide walks you through setting up Authelia authentication for your Launchpad Gateway.

Overview

Authelia provides:

• 🔐 Single Sign-On (SSO) for all your services
• 🛡️ Two-Factor Authentication (2FA) with TOTP/WebAuthn
• 🌐 Forward Authentication integration with Traefik
• 👥 User Management with file-based or LDAP backends
• 📧 Email Notifications for password resets and 2FA setup

Quick Start

1. Run the Setup Script

Windows (PowerShell):

.\setup-authelia.ps1

Linux/macOS (Bash):

chmod +x setup-authelia.sh
./setup-authelia.sh

2. Configure Your Environment

Edit .env file with your actual values:

DOMAIN=your-domain.com
TZ=America/New_York
ACME_EMAIL=admin@your-domain.com
AUTHELIA_JWT_SECRET=your_generated_jwt_secret
AUTHELIA_SESSION_SECRET=your_generated_session_secret

3. Update Authelia Configuration

Edit authelia/configuration.yml:

• Replace all instances of example.com with your actual domain
• Update SMTP settings if you want email notifications
• Adjust access control rules as needed

4. Set Up Users

Edit authelia/users_database.yml:

• Change the default password for admin user
• Add your own users
• Generate password hashes using:

  docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'your-password'
  

5. Start Services

docker-compose up -d

Access URLs

After setup, your services will be available at:

• Authelia Portal: https://auth.gate.YOUR_DOMAIN
• Traefik Dashboard: https://traefik.gate.YOUR_DOMAIN (requires authentication)
• Portainer: https://portainer.gate.YOUR_DOMAIN (requires authentication)
• Uptime Kuma: https://uptime.gate.YOUR_DOMAIN (requires authentication)

Default Credentials

⚠️ CHANGE THESE IMMEDIATELY!

• Username: admin
• Password: authelia

Configuration Files

authelia/configuration.yml

Main Authelia configuration with:

• Server settings
• Authentication backend (file-based by default)
• Access control rules
• Session configuration
• TOTP/WebAuthn settings

authelia/users_database.yml

User database when using file-based authentication:

• User credentials (hashed passwords)
• User groups
• Email addresses
• Display names

Access Control Rules

The default configuration includes:

• Bypass: Authelia portal itself
• Two-Factor: Admin services (Traefik, Portainer) for admins group
• One-Factor: Other services for any authenticated user

Example Rules

access_control:
  rules:
    # Public access
    - domain: 'public.gate.example.com'
      policy: 'bypass'
    
    # Admin-only with 2FA
    - domain: 
        - 'traefik.gate.example.com'
        - 'portainer.gate.example.com'
      policy: 'two_factor'
      subject:
        - 'group:admins'
    
    # Authenticated users
    - domain: '*.gate.example.com'
      policy: 'one_factor'

Adding New Protected Services

To protect a new service with Authelia:

1. Add the service to your docker-compose.yml
2. Add the Authelia middleware to the service labels:

   labels:
     - traefik.http.routers.myservice.middlewares=authelia,security-headers
   

SMTP Configuration

For email notifications (password reset, 2FA setup), configure SMTP in configuration.yml:

notifier:
  smtp:
    address: 'smtp://smtp.gmail.com:587'
    username: 'your-email@gmail.com'
    password: 'your-app-password'
    sender: 'Authelia <noreply@your-domain.com>'

Troubleshooting

Common Issues

1. "middleware authelia@docker not found"

   • Ensure Authelia container is running
   • Check that middleware is defined in Authelia labels

2. Login page not loading

   • Verify DNS resolves to your server
   • Check SSL certificate is valid
   • Ensure Authelia container is healthy

3. Authentication fails

   • Check user exists in users_database.yml
   • Verify password hash is correct
   • Check Authelia logs: docker-compose logs authelia

Logs

Check Authelia logs:

docker-compose logs -f authelia

Check Traefik logs:

docker-compose logs -f traefik

Security Considerations

1. Change Default Passwords: Update all default credentials immediately
2. Use Strong Secrets: Generate cryptographically secure JWT and session secrets
3. Enable 2FA: Configure TOTP or WebAuthn for sensitive services
4. Regular Updates: Keep Authelia and other containers updated
5. Monitor Logs: Regularly review authentication logs
6. Backup Configuration: Keep secure backups of your configuration files

Advanced Configuration

LDAP Integration

To use LDAP instead of file-based authentication, update configuration.yml:

authentication_backend:
  ldap:
    implementation: 'custom'
    address: 'ldap://your-ldap-server:389'
    base_dn: 'dc=example,dc=com'
    # ... additional LDAP settings

External Database

To use PostgreSQL or MySQL instead of SQLite:

storage:
  postgres:
    address: 'tcp://postgres:5432'
    database: 'authelia'
    username: 'authelia'
    password: 'your-password'

OIDC Provider

To use Authelia as an OIDC provider for other applications:

identity_providers:
  oidc:
    hmac_secret: 'your-hmac-secret'
    issuer_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
    clients:
      - id: 'myapp'
        secret: 'hashed-client-secret'
        redirect_uris:
          - 'https://myapp.example.com/callback'

Support

• Authelia Documentation
• Traefik Integration Guide
• Community Discord