Skip to content

Authelia SSO

Authelia provides Single Sign-On (SSO) with two-factor authentication for all charliehub services.

Overview

Property Value
Location hub2 (OVH Dedicated Server)
Container charliehub_authelia
Port 9091
URL https://auth.charliehub.net
Config /opt/charliehub/authelia/config/

How It Works

Authelia integrates with Traefik via ForwardAuth:

User Request → Traefik → ForwardAuth Check → Authelia
                                ↓
                    ┌───────────┴───────────┐
                    ↓                       ↓
              Authenticated            Not Authenticated
                    ↓                       ↓
              Forward to              Redirect to
              Backend Service         auth.charliehub.net

Protected Services

All services using the authelia@file middleware require authentication:

Service Domain
Docs docs.charliehub.net
Code Server code.charliehub.net
Traefik Dashboard traefik.charliehub.net
Prometheus prometheus.charliehub.net
Grafana grafana.charliehub.net
Domain Manager domains.charliehub.net
UniFi API unifi.charliehub.net

IP-Based Bypass

Certain networks can bypass authentication for specific services. This allows homelab VMs/CTs to access services programmatically without authentication.

Current Bypass Rules

# /opt/charliehub/authelia/config/configuration.yml
access_control:
  default_policy: two_factor
  rules:
    # Auth portal itself - always bypass
    - domain:
        - "auth.charliehub.net"
        - "auth.verdegris.ch"
        - "auth.sensemy.cloud"
        - "auth.microshare.eu"
      policy: bypass

    # Docs - bypass for homelab networks
    - domain: "docs.charliehub.net"
      policy: bypass
      networks:
        - REDACTED_SUBNET      # UK homelab LAN
        - REDACTED_SUBNET      # FR homelab LAN
        - 78.116.21.175/32  # FR site public WAN IP

Adding a New Bypass

To allow a network to bypass auth for a service:

  1. Edit the Authelia config: 

    sudo nano /opt/charliehub/authelia/config/configuration.yml

  2. Add a rule in the access_control.rules section: 

    - domain: "service.charliehub.net"
  policy: bypass
  networks:
    - REDACTED_SUBNET

  3. Restart Authelia: 

    cd /opt/charliehub && docker compose restart authelia

Important: Traffic Routing

For IP-based bypass to work, the client's source IP must be visible to Authelia. There are two scenarios:

Via WireGuard (Recommended) : Traffic routes through the WireGuard VPN, preserving the internal IP (10.x.x.x).

Via Public Internet : Traffic arrives from the site's public WAN IP. You must add the WAN IP to the bypass list.

WireGuard Routing (Configured)

hub2 connects to homelabs via WireGuard site-to-site VPN:

Interface Hub2 IP Routes To
wg-uk REDACTED_IP UK homelab (REDACTED_SUBNET)
wg-fr REDACTED_IP FR homelab (REDACTED_SUBNET)

Traffic from homelab devices to hub2 via WireGuard preserves their internal IPs, allowing IP-based bypass rules to work correctly.

Technical Architecture

The SSO bypass works when traffic arrives via WireGuard:

PX Node (REDACTED_IP)
    |
    | WireGuard tunnel via uk-ucg
    v
hub2 (wg-uk interface)
    |
    | Source IP preserved: REDACTED_IP
    v
Traefik :443
    |
    | Sets X-Forwarded-For
    v
Authelia (forwardAuth)
    |
    | Sees ip=REDACTED_IP, matches bypass rule
    v
Backend Service (e.g., docs-mkdocs)

Traefik Entrypoints:

  • websecure (:443) - All traffic (public + WireGuard)

User Management

Users are stored in /opt/charliehub/authelia/config/users_database.yml:

users:
  admin:
    displayname: "Admin"
    password: "$argon2id$v=19$m=65536,t=3,p=4$..."
    email: admin@example.com
    groups:
      - admins

Adding a User

  1. Generate a password hash: 

    docker exec charliehub_authelia authelia crypto hash generate argon2 --password 'yourpassword'

  2. Add to users_database.yml: 

    newuser:
  displayname: "New User"
  password: "<paste hash here>"
  email: newuser@example.com
  groups:
    - users

  3. Restart Authelia: 

    docker compose restart authelia

Two-Factor Authentication

TOTP (Time-based One-Time Password) is required by default. Users set up 2FA on first login using any authenticator app (Authy, Google Authenticator, 1Password, etc.).

Reset 2FA for a User

# Connect to SQLite database
docker exec -it charliehub_authelia sqlite3 /data/db.sqlite3

# Remove TOTP device for user
DELETE FROM totp_configurations WHERE username = 'username';

# Exit
.quit

User will be prompted to set up 2FA again on next login.

OIDC Identity Provider

Authelia can act as an OpenID Connect provider for SSO with external apps:

Configured Clients

Client Redirect URIs
Homarr homarr.charliehub.net
Proxmox px1-px5.charliehub.net

Adding an OIDC Client

  1. Generate a client secret: 

    docker exec charliehub_authelia authelia crypto hash generate argon2 --password 'client-secret'

  2. Add to configuration.yml under identity_providers.oidc.clients: 

    - client_id: "myapp"
  client_name: "My Application"
  client_secret: "<hashed secret>"
  redirect_uris:
    - "https://myapp.charliehub.net/callback"
  scopes:
    - openid
    - profile
    - email

  3. Restart Authelia.

Health Check

# Local
curl http://localhost:9091/api/health

# Public
curl https://auth.charliehub.net/api/health

Troubleshooting

Check Logs

docker logs charliehub_authelia --tail 100 -f

User Can't Login

  1. Check user exists in users_database.yml
  2. Verify password hash is correct
  3. Check Authelia logs for specific error

Bypass Not Working

  1. Check what IP Authelia sees: 
    docker logs charliehub_authelia 2>&1 | grep "domain.charliehub.net"
  2. Verify the remote_ip matches your bypass rules
  3. If IP is a public WAN IP, traffic is going via internet - see Traffic Routing

Session Issues

# Check Redis connection
docker exec charliehub_authelia_redis redis-cli ping

# Clear all sessions (nuclear option)
docker exec charliehub_authelia_redis redis-cli FLUSHALL