openreader/docs-site/docs/configure/auth.md at 522540452cd1a96e1e197a4240974fdd0ecb65c2

Richard R 522540452c feat(auth): add runtime toggle for user sign-ups and enforce signup policy

Introduce `enableUserSignups` runtime setting to allow administrators to control
whether new accounts can be created. Update environment variable and documentation
references to support this feature. UI elements for account creation are now
conditionally rendered based on this flag. Signup attempts are blocked server-side
when disabled, including email, OAuth, and anonymous upgrades.

Add `assertUserSignupAllowed` utility for consistent enforcement and corresponding
unit tests to verify policy behavior.

2026-05-14 12:47:05 -06:00

3.1 KiB

Raw Blame History

title
Auth

This page covers application-level configuration for provider access and authentication.

Auth behavior

Auth is enabled only when both BASE_URL and AUTH_SECRET are set.
Remove either value to disable auth.
Keep AUTH_TRUSTED_ORIGINS empty to trust only BASE_URL.
Anonymous auth sessions are disabled by default.
Set USE_ANONYMOUS_AUTH_SESSIONS=true to enable anonymous session flows.

Runtime modes

OpenReader effectively has three common runtime modes:

Auth disabled (BASE_URL or AUTH_SECRET unset): no admin panel. Shared providers can still exist via first-boot seeding (API_KEY/API_BASE), but you cannot manage them in-app.
Auth enabled, non-admin user: user account/session features are available, but no admin controls.
Auth enabled, admin user: full Settings → Admin access (shared providers + site features).

Admin role

When auth is enabled, you can designate one or more users as admins via the ADMIN_EMAILS env var:

ADMIN_EMAILS=alice@example.com,bob@example.com

Admins see a new Admin tab in Settings with two sub-tabs:

Shared TTS providers — server-managed TTS provider instances with encrypted keys, visible to all users.
Site features — runtime overrides for what were previously NEXT_PUBLIC_* build-time flags (including account signup availability, default TTS provider/model, word highlighting, audiobook export, etc.).

Admin assignment is reconciled on every session resolution, so removing an email from ADMIN_EMAILS demotes the user on next login without a restart. See Admin Panel for the full reference.

Route behavior

/ is a public landing/onboarding page and remains indexable.
/app is the protected app home (document list and uploader UI).
If auth is enabled and a valid session exists (including anonymous), visiting / redirects to /app.
Protected app routes continue to require auth; when anonymous sessions are disabled and no session exists, users are redirected to /signin.

For auth environment variables: Environment Variables
For admin role and shared TTS provider config: Admin Panel
For TTS character limits and quota behavior: TTS Rate Limiting
For provider-specific guidance: TTS Providers
For storage/S3/SeaweedFS behavior: Object / Blob Storage
For database mode: Database
For migration behavior and commands: Migrations

Sync notes

Auth enabled

Settings and reading progress are saved to the server.
Updates are not instant push-based sync; they use normal client polling/refresh behavior.
If two devices change the same item around the same time, the newest update wins.

Auth disabled

Settings and reading progress stay local in the browser (Dexie/IndexedDB).
This avoids no-auth cross-browser conflicts, but there is no cross-device sync.

You may still see old anonymous settings/progress available to claim from older deployments.

3.1 KiB Raw Blame History