Auth SSO

2 min read

Users and secrets

flowchart LR
    H[Host ./config] -->|bind mount| C[Container /config]
    H --> U[users_database.yml]
    H --> S[secrets directory]
    U --> F[File authentication backend]
    S --> E[Secret-file environment variables]
    S --> O[OIDC signing and client material]

Storage map

  • host service directory:
    • /home/loca/dev/services/authelia
  • Compose bind mount:
    • host ./config
    • container /config
  • user database:
    • host /home/loca/dev/services/authelia/config/users_database.yml
    • container /config/users_database.yml
    • authentication backend: file
  • secret directory:
    • host /home/loca/dev/services/authelia/config/secrets
    • container /config/secrets
  • other runtime state:
    • SQLite: /config/db.sqlite3
    • filesystem notifications: /config/notification.txt
    • README states generated secrets, user database, SQLite state, and notification output are intentionally ignored by Git

Ownership and inspection result

  • verified filesystem modes on 2026-08-27:
    • config/secrets: root-owned, mode 0700
    • config/users_database.yml: root-owned, mode 0600
  • unprivileged inspection:
    • reading the live user database returned Permission denied
    • no password hash or secret was read or copied into this wiki
    • no complete live username inventory is claimed
  • known bootstrap identity:
    • username loca
    • source: service README.md and the default argument in set-owner-password.sh

File-backend layout

  • structure defined by set-owner-password.sh:
    • root key: users
    • username key: loca by default
    • account fields:
      • disabled
      • displayname
      • password
      • email
      • groups
    • configured bootstrap group:
      • admins
  • password field:
    • stores an Argon2id digest
    • must never contain a plaintext password
    • must never be copied to this wiki, chat, ticket, or shell history
  • helper warning:
    • the current helper installs a complete replacement database containing one username
    • it is not a merge tool
    • use only through the approval-marked procedure in Operator runbook

Secret-file map

  • Compose environment reads:
    • session secret: /config/secrets/SESSION_SECRET
    • storage encryption key: /config/secrets/STORAGE_ENCRYPTION_KEY
    • reset-password JWT secret: /config/secrets/JWT_SECRET
    • OIDC HMAC secret: /config/secrets/OIDC_HMAC_SECRET
  • templated OIDC configuration reads:
    • signing private key: /config/secrets/oidc/jwks/private.pem
    • LiteLLM client-secret digest: /config/secrets/oidc/client-secret.digest
    • Coder client-secret digest: /config/secrets/oidc/coder-client-secret.digest
  • safe documentation rule:
    • path, owner, mode, and purpose may be documented
    • file contents, digests, tokens, cookies, private keys, and plaintext credentials must never be printed

If a secret might have leaked

  • immediate handling:
    • do not paste the suspected value anywhere else
    • identify which consuming subsystem uses the file
    • ask the operator before rotation, service restart, or destructive cleanup
  • reason:
    • rotation is a migration and service-change action
    • changing session or encryption secrets can invalidate sessions or make stored data unreadable
  • evidence handling:
    • record the path and incident time
    • do not record the value