yourwillyourwish/docs/BETTERAUTH_OAUTH_ADMIN_SETUP.md

BetterAuth OAuth Configuration - Admin Setup Guide

Overview

Your application uses BetterAuth framework for OAuth authentication. OAuth providers (Google, GitHub, Facebook, Discord) can be:

• ✅ Configured via /admin/setup page (recommended)
• ✅ Enabled/disabled dynamically without server restart
• ✅ Credentials saved to data/system-config.json

Quick Start

1. Access Admin Setup Page

http://localhost:3001/admin/setup

2. Scroll to "OAuth Providers (BetterAuth)" Section

You'll see 4 provider cards:

• 🔍 Google
• 🐙 GitHub
• 👍 Facebook
• 💬 Discord

3. For Each Provider You Want to Enable:

1. Check the "Enable [Provider] OAuth" checkbox
2. Enter Client ID and Client Secret
3. Click "💾 Save Settings"

---

Getting OAuth Credentials

🔍 Google OAuth Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a Project" → "New Project"
3. Enter project name: estate-platform
4. Click "Create"

Step 2: Enable OAuth 2.0

1. In sidebar, go to APIs & Services → Library
2. Search for "Google+ API"
3. Click it and click "Enable"

Step 3: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click "Create Credentials" → "OAuth client ID"
3. Choose application type: Web application
4. Name it: estate-platform-web

Step 4: Configure Redirect URIs

In the "Authorized redirect URIs" section, add:

http://localhost:3001/auth/google/callback

For production, also add:

https://yourdomain.com/auth/google/callback

Step 5: Copy Credentials

1. Click your created credential
2. Copy the Client ID and Client Secret
3. Paste them in the Google section on /admin/setup

---

🐙 GitHub OAuth Setup

Step 1: Register OAuth Application

1. Go to GitHub Developer Settings
2. Click "OAuth Apps" → "New OAuth App"
3. Fill in:
   • Application name: estate-platform
   • Homepage URL: http://localhost:3001
   • Authorization callback URL: http://localhost:3001/auth/github/callback

Step 2: Copy Credentials

1. You'll see Client ID immediately
2. Click "Generate a new client secret"
3. Copy both Client ID and Client Secret
4. Paste them in the GitHub section on /admin/setup

For Production:

Update the callback URL to:

https://yourdomain.com/auth/github/callback

---

👍 Facebook OAuth Setup

Step 1: Create Facebook App

1. Go to Facebook Developers
2. Click "My Apps" → "Create App"
3. Choose app type: Consumer
4. Fill in app details:
   • App Name: estate-platform
   • App Contact Email: your-email@example.com
   • Purpose: Select appropriate category

Step 2: Add Facebook Login Product

1. In app dashboard, click "Add Product"
2. Find "Facebook Login" and click "Set Up"
3. Choose platform: Web
4. Skip to "Settings"

Step 3: Configure OAuth Redirect URLs

1. In Facebook Login → Settings

2. Under "Valid OAuth Redirect URIs", add:

   http://localhost:3001/auth/facebook/callback
   

   For production:

   https://yourdomain.com/auth/facebook/callback
   

Step 4: Copy Credentials

1. Go to Settings → Basic
2. Copy App ID (use as Client ID)
3. Copy App Secret (use as Client Secret)
4. Paste them in the Facebook section on /admin/setup

---

💬 Discord OAuth Setup

Step 1: Create Discord Application

1. Go to Discord Developer Portal
2. Click "New Application"
3. Enter name: estate-platform
4. Accept terms and create

Step 2: Generate OAuth Credentials

1. In sidebar, click "OAuth2"
2. Under CLIENT INFORMATION, you'll see:
   • CLIENT ID (copy this)
   • Click "Reset Secret" to get CLIENT SECRET (copy this)

Step 3: Set Redirect URI

1. Under REDIRECTS, click "Add Redirect"
2. Enter: http://localhost:3001/auth/discord/callback
3. Click "Save Changes"

For production:

https://yourdomain.com/auth/discord/callback

Step 4: Paste Credentials

Copy Client ID and Client Secret to Discord section on /admin/setup

---

Configuration via Admin Setup Page

Location

/admin/setup

What You'll See

A clean 2x2 grid of OAuth provider cards:

┌─────────────────────────┬─────────────────────────┐
│ 🔍 Google               │ 🐙 GitHub               │
│                         │                         │
│ ☐ Enable Google OAuth   │ ☐ Enable GitHub OAuth   │
│ [Client ID input]       │ [Client ID input]       │
│ [Client Secret input]   │ [Client Secret input]   │
└─────────────────────────┴─────────────────────────┘
┌─────────────────────────┬─────────────────────────┐
│ 👍 Facebook             │ 💬 Discord              │
│                         │                         │
│ ☐ Enable Facebook OAuth │ ☐ Enable Discord OAuth  │
│ [App ID input]          │ [Client ID input]       │
│ [App Secret input]      │ [Client Secret input]   │
└─────────────────────────┴─────────────────────────┘

How to Configure

For Each Provider:

1. Check the checkbox to enable OAuth for that provider
2. Enter Client ID - The public identifier from the provider
3. Enter Client Secret - Keep this secret! Only use in secure environments
4. Click "💾 Save Settings" at the bottom

What Happens After Saving

• Credentials are saved to data/system-config.json
• BetterAuth automatically picks up the new configuration
• OAuth buttons appear on login page for enabled providers
• Users can immediately use OAuth sign-in

---

Testing OAuth Flow

Step 1: Enable at Least One Provider

Go to /admin/setup and enable Google (easiest to test)

Step 2: Visit Login Page

Go to http://localhost:3001 and click login button

Step 3: Click OAuth Button

Click "Continue with Google" button

Step 4: Verify Redirect

You should be redirected to Google's login page:

https://accounts.google.com/o/oauth2/v2/auth?client_id=...

Step 5: Complete Authentication

1. Sign in with your Google account
2. Grant permissions if prompted
3. You should be redirected back and logged in

---

Troubleshooting

OAuth Buttons Don't Show

Problem: No OAuth buttons on login page even after configuration Solutions:

1. Clear browser cache: Ctrl+Shift+Delete
2. Refresh page: Ctrl+R
3. Check admin setup page - provider might not be enabled
4. Verify JSON syntax in system-config.json

"Invalid Client ID" Error

Problem: Error when trying to use OAuth Solutions:

1. Verify Client ID is correct - copy from developer console again
2. Check spelling - no extra spaces
3. Ensure provider is enabled (checkbox checked)
4. Restart server: npm run dev

Redirect URI Mismatch

Problem: Provider says "redirect_uri mismatch" Solutions:

1. Verify exact callback URL in provider console:
   • Development: http://localhost:3001/auth/{provider}/callback
   • Production: https://yourdomain.com/auth/{provider}/callback
2. Check for typos - URLs are case-sensitive
3. Don't include query parameters
4. Save changes in provider console

"Invalid Client Secret"

Problem: Error during OAuth callback Solutions:

1. Double-check Client Secret - copy from provider console again
2. Ensure no extra spaces before/after
3. Verify it's not Client ID instead
4. Some providers show secret only once - regenerate if lost

Provider Not Responding

Problem: Redirect hangs or takes forever Solutions:

1. Check internet connection
2. Verify provider status page - provider may be down
3. Check firewall - may be blocking external requests
4. Check BETTER_AUTH_SECRET is set in .env

---

Environment Variables (Optional)

Instead of using admin setup page, you can set environment variables in .env:

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

# Facebook OAuth
FACEBOOK_CLIENT_ID=your-app-id
FACEBOOK_CLIENT_SECRET=your-app-secret

# Discord OAuth
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret

# BetterAuth Secret (REQUIRED)
BETTER_AUTH_SECRET=your-32-character-secret

Note: Admin setup page takes precedence over environment variables

---

Production Deployment

Important Security Notes:

1. Never commit credentials to Git
2. Use environment variables in production (not system-config.json)
3. Use HTTPS for all callback URLs
4. Enable CSRF protection (currently disabled for development)
5. Rotate secrets regularly

Callback URL Format:

https://yourdomain.com/auth/{provider}/callback

Replace with your actual domain for each provider!

Update Provider Consoles:

1. Google Cloud Console
2. GitHub OAuth App Settings
3. Facebook App Settings
4. Discord Developer Portal

All must have production URL as redirect URI.

---

File Locations

Configuration Storage

data/system-config.json

Example structure:

{
  "oauth": {
    "google": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    },
    "github": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    },
    "facebook": {
      "enabled": true,
      "clientId": "YOUR_APP_ID",
      "clientSecret": "YOUR_APP_SECRET"
    },
    "discord": {
      "enabled": true,
      "clientId": "YOUR_CLIENT_ID",
      "clientSecret": "YOUR_CLIENT_SECRET"
    }
  }
}

BetterAuth Configuration

lib/auth.ts

Admin Setup Page

app/admin/setup/page.tsx

OAuth Callback Routes

app/auth/google/callback/route.ts
app/auth/github/callback/route.ts
app/auth/facebook/callback/route.ts
app/auth/discord/callback/route.ts

Frontend Login Modal

components/auth/AuthModal.tsx

---

Summary

✅ OAuth is configured via BetterAuth framework ✅ Admin setup page at /admin/setup for easy configuration ✅ Support for 4 major OAuth providers ✅ Enable/disable providers without server restart ✅ Credentials saved in system-config.json

For detailed setup of each provider, follow the step-by-step guides above!