Authentication with Better Auth in Makerkit Next.js Prisma

This module covers Makerkit's authentication system using Better Auth and adds Google OAuth sign-in to TeamPulse.

Technologies used:

• Better Auth - Authentication framework
• Prisma ORM - Database tables for auth

What you'll accomplish:

• Understand the existing auth system
• Add Google OAuth sign-in
• Test the complete auth flow

Understanding the Auth System

Makerkit uses Better Auth, a TypeScript-first authentication framework.

Auth Pages

Key Configuration Files

How It Works

1. Sign-up flow:
   • User submits email/password
   • Account created in users table
   • Verification email sent (check Mailpit at http://localhost:8025)
   • User clicks link → signed in
   • Organization auto-created (only in B2B mode)
2. Sign-in flow:
   • User submits credentials
   • Session created in session table
   • Cookie set for authentication
   • Redirected to /dashboard
3. Session access:
   // Server-side (in server actions, loaders, pages)
   import { getSession } from '@kit/better-auth/context';
   const session = await getSession();
   const userId = session?.user?.id;

Checkpoint: Test the Existing Flow

Before adding OAuth, verify email/password auth works:

1. Go to /auth/sign-up
2. Create a new account
3. Check Mailpit for new emails at http://localhost:8025
4. Click the verification link
5. Confirm you land on the dashboard

If you seeded test data using pnpm seed, you can also sign in with user1@makerkit.dev / testingpassword.

Adding Google OAuth

Step 1: Create Google Cloud Credentials

1. Go to Google Cloud Console

2. Create a new project (or select existing)

3. Navigate to APIs & Services → Credentials

4. Click Create Credentials → OAuth client ID

5. Select Web application

6. Add authorized redirect URI:

   http://localhost:3000/api/auth/callback/google

   Note: For production, use https:// and your actual domain (e.g., https://yourdomain.com/api/auth/callback/google). OAuth providers require HTTPS for production redirect URIs.

7. Copy the Client ID and Client Secret

Step 2: Configure Environment Variables

Add to apps/web/.env.local:

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
# Enable Google in the OAuth providers list
NEXT_PUBLIC_AUTH_OAUTH_PROVIDERS=google

Important: In production, use a secrets manager instead of environment files for sensitive values.

Step 3: Test

Visit /auth/sign-in. You should see a "Sign in with Google" button.

1. Click "Sign in with Google"
2. Complete Google's sign-in
3. You're redirected back and signed in

How OAuth Works in Makerkit

The Plugin System

Better Auth uses plugins for OAuth providers. Configuration lives in packages/better-auth/src/plugins/social-providers.ts.

When you set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, the plugin automatically:

• Handles the OAuth redirect flow
• Creates or links user accounts
• Manages OAuth tokens securely

Adding Other Providers

Please refer to the documentation to add social providers.

Additional Auth Features

Magic Links (Passwordless)

Let users sign in via email link - no password needed.

• Enable: NEXT_PUBLIC_AUTH_MAGIC_LINK=true

Password Requirements

Enforce stronger passwords with special characters, numbers, uppercase.

• Configure: (all default to false)
  NEXT_PUBLIC_PASSWORD_REQUIRE_SPECIAL_CHARS=true
  NEXT_PUBLIC_PASSWORD_REQUIRE_NUMBERS=true
  NEXT_PUBLIC_PASSWORD_REQUIRE_UPPERCASE=true

Custom Email Templates

Customize verification, password reset, and invitation emails.

• Templates: packages/email-templates/src/emails/ (React Email components)

Captcha Protection

Add Cloudflare Turnstile to prevent bot sign-ups.

• Configure:
  NEXT_PUBLIC_CAPTCHA_SITE_KEY=your-site-key
  TURNSTILE_SECRET_KEY=your-secret

• Docs: Better Auth Captcha

Module Complete

You now have:

• [x] Understanding of Makerkit's auth architecture
• [x] Google OAuth sign-in working
• [x] Awareness of advanced auth features (MFA, magic links, captcha, etc.)

Next: In Module 7: Organizations & Teams, you'll apply role-based access control to TeamPulse features.

Learn More

• Authentication Documentation
• Better Auth Documentation
• Better Auth Plugins
• Google OAuth Setup Guide