Files
eleith 4256c0fb49
ci/woodpecker/pr/config Pipeline was successful
ci/woodpecker/pr/web Pipeline was successful
ci/woodpecker/pr/worker Pipeline was successful
ci/woodpecker/push/config Pipeline was successful
ci/woodpecker/push/web Pipeline was successful
ci/woodpecker/push/worker Pipeline was successful
feat(auth): generate a session secret when none is configured
2026-11-12 14:33:59 -08:00

39 lines
1.8 KiB
Markdown

# Authentication
One deployment serves one journal. Sign-in is required, and every admitted user
has the same access to reports and explicit financial jobs.
## Setup
Use the [configuration example](../apps/web/config/hledger-reports.example.yaml).
Choose exactly one strategy: credentials or OIDC.
- Set `url.app` to the exact browser origin. `localhost` and `127.0.0.1` are different origins.
- Use a strong password for credentials sign-in.
- The session key uses `auth.secret`, then a nonempty `AUTH_SECRET`, otherwise a random key generated at startup. Set a stable random secret of at least 32 characters to stay signed in across restarts.
- Keep secrets out of commits, command arguments and logs. Restart services after configuration changes.
For OIDC, set the issuer, client ID and client secret. Register
`<url.app>/auth/callback/oidc` with the provider and restrict admission there; the
app has no separate user allowlist. Sign-out clears the app session, not the
provider session.
## Trusted proxy
Compiled web requires a trusted HTTPS proxy. Only that proxy may reach the
upstream. Preserve the public `Host` and overwrite `X-Forwarded-Proto` and
`X-Real-IP` with trusted values, never browser-supplied headers.
Set `APP_URL` to the public HTTPS origin when using the Compose example. Use Vite
development for direct local HTTP access. Do not expose the upstream publicly.
## Sessions
Authentication cookies use an `hledger-` prefix scoped to the configured public
port, preventing accidental collisions between local apps and instances.
Without a supplied secret, restarting web signs users out. Sessions survive restart
with the same configured or environment secret. Changing a password or provider
assignment does not immediately revoke existing sessions. Rotate the auth secret
and restart web to sign everyone out. Local sign-out cannot revoke copied cookies.