Auth SSO

5 min read

Operator runbook

flowchart TD
    A[Problem reported] --> B{Health endpoint works?}
    B -->|no| C[Inspect Compose state and logs]
    B -->|yes| D{Portal opens?}
    D -->|no| E[Restore Nginx backup]
    D -->|yes| F{Password accepted?}
    F -->|no| G[Reset owner password]
    F -->|yes| H{Protected app loops?}
    H -->|yes| I[Check cookie domain, clock, and auth snippets]
    H -->|no| J[Service is usable]

Approval labels

  • ASK FIRST:
    • stop and obtain operator approval before pasting the command
    • applies to deploys, destructive filesystem work, Nginx configuration, system-service changes, and domain/certificate work under /home/loca/AGENTS.md
  • READ ONLY:
    • no listed ask-first stop
    • still read the command before pasting it
  • deployment note:
    • the 2026-08-27 validation, restart, health, and installation results are recorded as completed evidence; commands below remain operator procedures

Validate the active Authelia configuration

  • purpose:
    • ask the running v4.39.20 binary to parse and validate the bind-mounted file
    • catches invalid YAML, invalid duration values, and invalid theme values such as forest
  • approval: READ ONLY
cd /home/loca/dev/services/authelia && sudo -n docker compose exec -T authelia authelia config validate --config /config/configuration.yml

Restart Authelia

  • purpose:
    • make an already-approved configuration change active
  • approval: ASK FIRST — service restart / deploy action
cd /home/loca/dev/services/authelia && sudo -n docker compose restart authelia
  • immediately follow with the health check below

Check container state and health

  • purpose:
    • show Compose state
    • call the loopback health endpoint already documented by the service
  • approval: READ ONLY
cd /home/loca/dev/services/authelia && sudo -n docker compose ps authelia
curl --fail --silent --show-error http://127.0.0.1:51091/api/health
  • expected:
    • Compose shows authelia running
    • curl exits 0

Tail Authelia logs

  • purpose:
    • watch startup, validation, authentication, and authorization failures
  • approval: READ ONLY
cd /home/loca/dev/services/authelia && sudo -n docker compose logs --tail=200 --follow authelia
  • stop following:
    • press Ctrl-C
    • stopping the log viewer does not stop Authelia
  • secret rule:
    • do not paste log lines containing user, token, cookie, or secret material into public chat

Reset the owner password

  • purpose:
    • run the repository helper for the owner username loca
  • approval: ASK FIRST — destructive filesystem write plus Authelia restart
  • critical behavior:
    • set-owner-password.sh rewrites the entire users_database.yml
    • it does not merge another user into the file
    • do not use it if additional accounts must be preserved until the operator has backed them up safely
cd /home/loca/dev/services/authelia && ./set-owner-password.sh loca
  • interactive flow:
    • Authelia prompts twice for the new password
    • copy only the generated Argon2 digest into the helper prompt
    • helper installs the digest-only database and restarts Authelia
  • never record:
    • plaintext password
    • Argon2 digest
    • contents of users_database.yml

Installed rollback backups

  • created by the 2026-08-27 install:
    • portal vhost: /etc/nginx/sites-available/auth.loca.zone.bak-20260827T081046Z
    • Authelia configuration: /home/loca/dev/services/authelia/config/configuration.yml.bak-20260827T081155Z
  • rule:
    • restore the timestamped .bak-* file created at install
    • do not substitute an unverified backup name

Roll back portal injection

  • purpose:
    • restore the pre-change portal vhost
    • validate all installed Nginx configuration before reload
  • approval: ASK FIRST — Nginx config replacement and system-service reload
sudo -n install -m 0644 -o root -g root /etc/nginx/sites-available/auth.loca.zone.bak-20260827T081046Z /etc/nginx/sites-available/auth.loca.zone &&
sudo -n /usr/sbin/nginx -t &&
sudo -n systemctl reload nginx
  • gate:
    • the && chain prevents reload when install or validation fails
    • do not bypass that gate
  • cleanup:
    • do not delete /var/www/auth-portal during incident recovery
    • unreferenced asset files are inert and can be reviewed later

Roll back session values and theme from the timestamped .bak-*

  • purpose:
    • restore the full pre-change Authelia file
    • validate it with the container binary
    • restart only after validation succeeds
  • approval: ASK FIRST — configuration replacement and service restart
sudo -n install -m 0644 -o root -g root /home/loca/dev/services/authelia/config/configuration.yml.bak-20260827T081155Z /home/loca/dev/services/authelia/config/configuration.yml &&
cd /home/loca/dev/services/authelia && sudo -n docker compose exec -T authelia authelia config validate --config /config/configuration.yml &&
cd /home/loca/dev/services/authelia && sudo -n docker compose restart authelia
  • gate:
    • the && chain prevents restart when restore or validation fails
    • do not bypass that gate
  • restored historical values expected from this 2026-08-27 backup:
    • theme: auto
    • expiration: 1h
    • inactivity: 5m
    • remember_me: 1M

If you lock yourself out

  • step 1, distinguish service failure from credential failure
  • approval: READ ONLY
curl --fail --silent --show-error http://127.0.0.1:51091/api/health
curl --silent --show-error --output /dev/null --write-out '%{http_code} %{url_effective}\n' https://auth.loca.zone/
  • interpret:
    • health fails: inspect Compose state and logs
    • health works but portal fails: restore the timestamped Nginx .bak-* file
    • portal works but password fails: use the owner-password helper after approval
    • login works but a protected app loops: use Troubleshooting
  • step 2, emergency restore of both timestamped .bak-* files
  • approval: ASK FIRST — Nginx replacement, Authelia replacement, reload, and restart
sudo -n install -m 0644 -o root -g root /etc/nginx/sites-available/auth.loca.zone.bak-20260827T081046Z /etc/nginx/sites-available/auth.loca.zone &&
sudo -n install -m 0644 -o root -g root /home/loca/dev/services/authelia/config/configuration.yml.bak-20260827T081155Z /home/loca/dev/services/authelia/config/configuration.yml &&
sudo -n /usr/sbin/nginx -t &&
cd /home/loca/dev/services/authelia && sudo -n docker compose exec -T authelia authelia config validate --config /config/configuration.yml &&
sudo -n systemctl reload nginx &&
cd /home/loca/dev/services/authelia && sudo -n docker compose restart authelia
  • stop conditions:
    • no backup file: do not invent one
    • failed Nginx validation: do not reload Nginx
    • failed Authelia validation: do not restart Authelia
  • safe access point:
    • use a terminal on this host; do not depend on a protected web app while repairing its gate