hledger-web-reports/docs/authentication.md

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. 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.