Authentication with Better Auth in Makerkit Next.js Prisma

In this module, you'll understand how Makerkit's authentication works and add Google OAuth sign-in to TeamPulse.

In this module, I want to walk through all you need to know about authentication in Makerkit using Better Auth - and how to dive in into the internals of the authentication system by linking to the documentation.

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. Before adding features, let's understand what's already configured.

Auth Pages

Navigate through the existing auth pages:

Try it: Visit each page in your browser to see the UI.

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 sessions 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

Let's add "Sign in with Google" to TeamPulse.

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

NB: when you go to production, please do not use the env file for storing secret environment variables.

Step 3: Test

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

Test the flow:

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.

The configuration lives in packages/better-auth/src/plugins/social-providers.ts - and should be modified if you require other Social providers.

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.

What Else Is Possible

The auth system has many more features you can enable. Here's what's available:

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 6 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

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