# Authentication Configuration

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

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/better-auth/overview*

---

Ship secure authentication without managing auth infrastructure or paying per-user fees. [Better Auth](https://www.better-auth.com/) 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](https://orm.drizzle.team/) 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](https://www.better-auth.com/) 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

| Page | Purpose |
|------|---------|
| [Setup](./setup) | Core configuration and database adapter |
| [Auth Methods](./auth-methods) | Email/password and magic link settings |
| [Social Providers](./social-providers) | OAuth configuration (Google by default, others via extension) |
| [MFA Configuration](./mfa-configuration) | TOTP-based multi-factor authentication |
| [Adding Plugins](./adding-plugins) | Extend Better Auth with plugins |
| [Captcha Plugin](./captcha-plugin) | Bot protection with Cloudflare Turnstile |
| [OTP Plugin](./otp-plugin) | Email-based one-time passwords |
| [Rate Limiting](./rate-limiting) | Protect against brute force attacks |
| [One-Time Token Plugin](./one-time-token-plugin) | Secure verification codes |
| [Admin Plugin](./admin-plugin) | User management and impersonation |

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "How is Better Auth different from Auth.js (NextAuth)?", "answer": "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."},
     {"question": "Where is the Better Auth configuration?", "answer": "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."},
     {"question": "Can I use a different database?", "answer": "Yes. Better Auth uses Drizzle ORM, which supports PostgreSQL, MySQL, and SQLite. Change the Drizzle adapter configuration and connection strings."},
     {"question": "How do I add a custom OAuth provider?", "answer": "Create a plugin file in packages/better-auth/src/plugins/, configure the provider with Better Auth social providers API, and add credentials to .env."},
     {"question": "Is session data stored in cookies or the database?", "answer": "Better Auth stores session tokens in HTTP-only cookies and session data in your PostgreSQL database via Drizzle. This allows session invalidation across devices."},
     {"question": "How do I customize the sign-in UI?", "answer": "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 →](./setup)