Initial commit
This commit is contained in:
Developer
395
docs/BETTERAUTH_OAUTH_ADMIN_SETUP.md
Normal file
395
docs/BETTERAUTH_OAUTH_ADMIN_SETUP.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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](https://console.cloud.google.com/)
|
||||
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](https://github.com/settings/developers)
|
||||
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](https://developers.facebook.com/)
|
||||
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](https://discord.com/developers/applications)
|
||||
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`:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"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!
|
||||
Reference in New Issue
Block a user