Authentication System#

LobeHub's self-hosted authentication is built on Better Auth. The central configuration lives in src/libs/better-auth/define-config.ts, which assembles the full Better Auth instance from environment-driven options, database adapters, plugins, and SSO providers.

Authentication strategies are entirely controlled through environment variables — no code changes are needed to switch between modes. All auth env vars are declared and validated (via Zod + @t3-oss/env-core) in packages/env/src/auth.ts.

Authentication Modes#

Email/Password (default)#

Email/password login is enabled by default 1. The Better Auth config exposes it via the emailAndPassword block:

• Passwords are 8–64 characters 2
• Bcrypt hashes from Clerk migrations are supported alongside Better Auth's default scrypt 3
• Email verification is opt-in via AUTH_EMAIL_VERIFICATION=1 4
• Magic link (passwordless) login is opt-in via AUTH_ENABLE_MAGIC_LINK=1 5; expires in 15 minutes 6
• Password-reset and verification emails require SMTP configuration 7 8

SSO-Only Mode#

Setting AUTH_DISABLE_EMAIL_PASSWORD=1 disables email/password login entirely 9. When active 10:

• The email field is hidden on the login page
• The signup page redirects to login
• Users must authenticate through a configured SSO provider

⚠️ Ensure at least one SSO provider is configured via AUTH_SSO_PROVIDERS before enabling SSO-only mode, or users will have no login path 11.

SSO Provider Configuration#

Providers are enabled by setting AUTH_SSO_PROVIDERS to a comma-separated list of provider IDs 12. The order determines display order on the login page.

Supported providers (each requires a corresponding AUTH_<PROVIDER>_ID / AUTH_<PROVIDER>_SECRET, and OIDC providers also need AUTH_<PROVIDER>_ISSUER) 13:

Internally, initBetterAuthSSOProviders() resolves each provider name against a registry, validates required env vars, and routes them to either socialProviders (built-in) or genericOAuthProviders (OIDC). The parsed provider list is also used as the trustedProviders for account linking, allowing accounts with different emails to be merged 14.

Key Environment Variables#

Full variable reference: docs/self-hosting/environment-variables/auth.mdx

Additional Features#

Passkeys — enabled unconditionally via the @better-auth/passkey plugin; rpID and origin are derived from APP_URL 24.

Email OTP (mobile) — the emailOTP plugin issues 6-digit codes expiring in 5 minutes for Expo/React Native clients; OTP is not auto-sent on signup 25.

Email whitelist — the custom emailWhitelist() plugin enforces AUTH_ALLOWED_EMAILS at user-creation time for both email signup and SSO flows, blocking registration with an EMAIL_NOT_ALLOWED error for unauthorized emails 26.

Session storage — sessions are stored both in PostgreSQL (via Drizzle) and a Redis secondary storage for performance; cookie-level cache has a 2-minute TTL 27.

User bootstrap — a databaseHooks.user.create.after hook calls UserService.initUser() for every new account regardless of sign-up method 28.

Rate limiting — password-reset and email-verification endpoints are capped at 3 requests per 60 seconds 29.

Key Source Files#