Authentication Configuration

Configure Better Auth for authentication, session management, MFA, and security settings in your SaaS application.

Ship secure authentication without managing auth infrastructure or paying per-user fees. Better Auth handles sessions, OAuth, MFA, and password flows - all self-hosted in your TanStack Start app.

The TanStack Start Drizzle SaaS Kit uses Better Auth for authentication with Drizzle ORM as the database adapter. Better Auth runs entirely on your infrastructure - no external auth service, no per-seat pricing. Configure email/password, magic links, OAuth providers, and MFA through environment variables. The kit includes pre-built sign-in forms, password reset flows, account deletion, and session management out of the box.

Better Auth is a TypeScript-first, self-hosted authentication library that provides session management, OAuth integration, MFA, and multi-tenancy plugins without external dependencies.

Use this documentation when: you're setting up authentication for the first time, adding a new OAuth provider, enabling MFA, or customizing auth behavior.

Avoid modifying auth internals when: the default configuration meets your needs. Better Auth's defaults are secure and production-ready.

If unsure: start with email/password authentication enabled. Add OAuth and MFA after your core app works.

Features

  • Email/password authentication
  • Magic link (passwordless) authentication
  • Multi-factor authentication (MFA/TOTP)
  • OAuth providers (Google by default, others via extension)
  • Secure session management
  • Password reset flows
  • Account deletion with verification
  • Rate limiting and captcha protection

Why Better Auth?

  • Self-Hosted - Runs on your infrastructure with no external auth service
  • No Per-User Pricing - Unlimited users without SaaS auth costs
  • TypeScript-First - Full type safety across client and server
  • Database Agnostic - Works with Drizzle ORM and PostgreSQL (or any Drizzle-supported database)
  • Plugin Architecture - Add MFA, OAuth, rate limiting as needed
  • Production Ready - Industry-standard security practices

Common Pitfalls

  • Forgetting to set BETTER_AUTH_SECRET: Sessions won't work without a 32+ character secret. Generate one with openssl rand -base64 32.
  • Mismatched OAuth redirect URLs: Your VITE_SITE_URL must exactly match what's configured in Google/GitHub OAuth settings.
  • Skipping email verification in production: Always require email verification to prevent account takeover.
  • Not enabling rate limiting: Auth endpoints are prime targets for brute force. Keep rate limiting enabled in production.
  • Storing secrets in .env instead of .env: Auth secrets should never be committed. Use .env for BETTER_AUTH_SECRET and OAuth credentials.
  • Testing MFA with production authenticator apps: Use a separate authenticator entry for development to avoid lockouts.

Documentation Structure

PagePurpose
SetupCore configuration and database adapter
Auth MethodsEmail/password and magic link settings
Social ProvidersOAuth configuration (Google by default, others via extension)
MFA ConfigurationTOTP-based multi-factor authentication
Adding PluginsExtend Better Auth with plugins
Captcha PluginBot protection with Cloudflare Turnstile
OTP PluginEmail-based one-time passwords
Rate LimitingProtect against brute force attacks
One-Time Token PluginSecure verification codes
Admin PluginUser management and impersonation

Frequently Asked Questions

How is Better Auth different from Auth.js (NextAuth)?
Better Auth is fully self-hosted with no external dependencies, offers built-in multi-tenancy plugins, and provides a more flexible plugin architecture. Auth.js relies on adapters and has different session handling.
Where is the Better Auth configuration?
The main configuration lives in packages/better-auth/src/auth.ts. Plugins are in packages/better-auth/src/plugins/. Client-side auth is in packages/better-auth/src/auth-client.ts.
Can I use a different database?
Yes. Better Auth uses Drizzle ORM, which supports PostgreSQL, MySQL, and SQLite. Change the Drizzle adapter configuration and connection strings.
How do I add a custom OAuth provider?
Create a plugin file in packages/better-auth/src/plugins/, configure the provider with Better Auth social providers API, and add credentials to .env.
Is session data stored in cookies or the database?
Better Auth stores session tokens in HTTP-only cookies and session data in your PostgreSQL database via Drizzle. This allows session invalidation across devices.
How do I customize the sign-in UI?
The sign-in forms are in packages/auth/src/components/. They use the @kit/ui component library. Modify the components directly - they are standard React components with Tailwind CSS.

Next: Better Auth Setup →