PromptTech/docs/AUTH_SETUP_GUIDE.md

# PromptTech Solutions - Authentication Setup Guide

## Complete OAuth & Email Verification Implementation

This guide will walk you through setting up Google OAuth, Facebook OAuth, Yahoo OAuth, and Gmail SMTP for email verification.

---

## 📋 Table of Contents

1. [Google OAuth Setup](#1-google-oauth-setup)
2. [Gmail SMTP Setup](#2-gmail-smtp-setup)
3. [Facebook OAuth Setup](#3-facebook-oauth-setup)
4. [Yahoo OAuth Setup](#4-yahoo-oauth-setup)
5. [Backend Configuration](#5-backend-configuration)
6. [Testing the Implementation](#6-testing-the-implementation)

---

## 1. Google OAuth Setup

### Step 1.1: Create Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click "Select a project" → "NEW PROJECT"
3. Project Name: `PromptTech Solutions`
4. Click "CREATE"

### Step 1.2: Enable Google+ API

1. In your project, go to **APIs & Services** → **Library**
2. Search for "Google+ API"
3. Click on it and press **ENABLE**

### Step 1.3: Create OAuth 2.0 Credentials

1. Go to **APIs & Services** → **Credentials**
2. Click **CREATE CREDENTIALS** → **OAuth client ID**
3. If prompted, configure OAuth consent screen first:
   - User Type: **External**
   - App name: `PromptTech Solutions`
   - User support email: `prompttechbz@gmail.com`
   - Developer contact: `prompttechbz@gmail.com`
   - Click **SAVE AND CONTINUE**
   - Scopes: Add `.../auth/userinfo.email` and `.../auth/userinfo.profile`
   - Click **SAVE AND CONTINUE**
   - Test users: Add your Gmail address
   - Click **SAVE AND CONTINUE**

4. Back to Credentials → **CREATE CREDENTIALS** → **OAuth client ID**
   - Application type: **Web application**
   - Name: `PromptTech Web Client`
   - Authorized JavaScript origins:
     - `http://localhost:5300`
     - `http://prompttech.dynns.com:5300`
     - `https://prompttech.dynns.com` (if you have SSL)
   - Authorized redirect URIs:
     - `http://localhost:8181/api/auth/google/callback`
     - `http://prompttech.dynns.com:8181/api/auth/google/callback`
   - Click **CREATE**

5. **SAVE THESE CREDENTIALS:**
   - Client ID: `xxxxxxxx-xxxxxxxx.apps.googleusercontent.com`
   - Client Secret: `GOCSPX-xxxxxxxxxxxxxxxxxx`

---

## 2. Gmail SMTP Setup (For Email Verification)

### Option A: Using Gmail Account (Personal - Recommended for Testing)

1. Go to your Gmail account settings
2. Click **Security** (left sidebar)
3. Enable **2-Step Verification** (if not already enabled)
4. After enabling 2FA, go back to Security
5. Click **App passwords** (you'll only see this after enabling 2FA)
6. Select app: **Mail**
7. Select device: **Other (Custom name)**
8. Enter: `PromptTech Solutions`
9. Click **GENERATE**
10. **SAVE THIS 16-CHARACTER PASSWORD** (example: `abcd efgh ijkl mnop`)

**Important Notes:**

- This is NOT your Gmail password
- This is a special app-specific password
- You'll use this in your `.env` file

### Option B: Using Google Workspace (Business - Recommended for Production)

If you want a professional email (e.g., `no-reply@prompttech.com`):

1. Sign up for [Google Workspace](https://workspace.google.com/)
   - Cost: ~$6/month per user
   - Benefits: Professional email, no "sent via Gmail" footer
2. Create an account like `no-reply@prompttech.com`
3. Follow the same App Password steps as Option A

**For now, use Option A (personal Gmail) to test everything.**

---

## 3. Facebook OAuth Setup

### Step 3.1: Create Facebook App

1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Click **My Apps** → **Create App**
3. Select **Consumer** → **Next**
4. App Name: `PromptTech Solutions`
5. App Contact Email: `prompttechbz@gmail.com`
6. Click **Create App**

### Step 3.2: Configure Facebook Login

1. In your app dashboard, click **Add Product**
2. Find **Facebook Login** → **Set Up**
3. Select **Web** platform
4. Site URL: `http://localhost:5300` (for testing)
5. Click **Save** → **Continue**

### Step 3.3: Configure OAuth Settings

1. Go to **Facebook Login** → **Settings** (left sidebar)
2. Valid OAuth Redirect URIs:

   ```
   http://localhost:8181/api/auth/facebook/callback
   http://prompttech.dynns.com:8181/api/auth/facebook/callback
   ```

3. Click **Save Changes**

### Step 3.4: Get App Credentials

1. Go to **Settings** → **Basic** (left sidebar)
2. **SAVE THESE:**
   - App ID: `1234567890123456`
   - App Secret: Click **Show** → `abc123def456ghi789jkl012mno345pq`

### Step 3.5: Make App Live (Important!)

1. At the top of dashboard, toggle from **Development** to **Live**
2. You may need to complete App Review for full production use

---

## 4. Yahoo OAuth Setup

### Step 4.1: Create Yahoo App

1. Go to [Yahoo Developer Network](https://developer.yahoo.com/)
2. Sign in with your Yahoo account
3. Click **My Apps** → **Create an App**
4. App Name: `PromptTech Solutions`
5. Application Type: **Web Application**
6. Home Page URL: `http://localhost:5300`
7. Redirect URI(s):

   ```
   http://localhost:8181/api/auth/yahoo/callback
   http://prompttech.dynns.com:8181/api/auth/yahoo/callback
   ```

8. API Permissions: Select **OpenID Connect**
9. Click **Create App**

### Step 4.2: Get App Credentials

1. After creating the app, you'll see:
   - Client ID (Consumer Key): `dj0yJmk9xxxxxxxxxx`
   - Client Secret (Consumer Secret): Click **Show** → `abcdef123456789`

2. **SAVE THESE CREDENTIALS**

---

## 5. Backend Configuration

### Step 5.1: Update `.env` File

Create or update `/backend/.env` with all your credentials:

```env
# JWT Secret (generate a random string)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# Email Configuration (Gmail SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=prompttechbz@gmail.com
SMTP_PASSWORD=abcd efgh ijkl mnop    # Your 16-char App Password from Step 2
FROM_EMAIL=prompttechbz@gmail.com

# Frontend URL (where users will be redirected)
FRONTEND_URL=http://localhost:5300

# Google OAuth
GOOGLE_CLIENT_ID=xxxxxxxx-xxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=http://localhost:8181/api/auth/google/callback

# Facebook OAuth
FACEBOOK_APP_ID=1234567890123456
FACEBOOK_APP_SECRET=abc123def456ghi789jkl012mno345pq
FACEBOOK_REDIRECT_URI=http://localhost:8181/api/auth/facebook/callback

# Yahoo OAuth
YAHOO_CLIENT_ID=dj0yJmk9xxxxxxxxxx
YAHOO_CLIENT_SECRET=abcdef123456789
YAHOO_REDIRECT_URI=http://localhost:8181/api/auth/yahoo/callback
```

### Step 5.2: Install Required Python Packages

```bash
cd /media/pts/Website/PromptTech_Solution_Site/backend
pip install authlib httpx python-multipart itsdangerous
```

These packages are for:

- `authlib`: OAuth library
- `httpx`: Async HTTP client
- `python-multipart`: For form data
- `itsdangerous`: Token generation

### Step 5.3: Update Database Model

The User model needs these additional fields (should already be in models.py):

- `email_verified`: Boolean
- `verification_token`: String (optional)
- `oauth_provider`: String (google, facebook, yahoo, email)

---

## 6. Testing the Implementation

### Test Email Verification

1. Start backend: `cd scripts && ./start_backend.sh`
2. Start frontend: `npm run build` (since you're using nginx)
3. Go to `http://localhost:5300/login`
4. Click "Sign up"
5. Fill in:
   - First Name: John
   - Last Name: Doe
   - Email: <your-test-email@gmail.com>
   - Password: test123
6. Click "Create Account"
7. Check your email for verification link
8. Click the verification link
9. You should be redirected and logged in

### Test Google OAuth

1. On login page, click "Sign in with Google"
2. Select your Google account
3. Grant permissions
4. Should redirect back and log you in

### Test Facebook OAuth

1. On login page, click "Sign in with Facebook"
2. Log in to Facebook (if not already)
3. Grant permissions
4. Should redirect back and log you in

### Test Yahoo OAuth

1. On login page, click "Sign in with Yahoo"
2. Log in to Yahoo account
3. Grant permissions
4. Should redirect back and log you in

---

## 🚨 Important Security Notes

### For Production Deployment

1. **Change JWT Secret**: Generate a strong random key

   ```bash
   python -c "import secrets; print(secrets.token_urlsafe(64))"
   ```

2. **Use HTTPS**: Update all URLs to `https://`

3. **Environment Variables**: Never commit `.env` file to git

4. **App Passwords**: Store securely, rotate periodically

5. **OAuth Scopes**: Only request necessary permissions

6. **Rate Limiting**: Add rate limiting to prevent abuse

7. **CORS**: Configure properly for production domain

---

## 📞 Need Help?

If you encounter issues:

1. **Check logs**: `tail -f backend/logs/*.log`
2. **Test email**: Send a test email using Python SMTP
3. **OAuth errors**: Check redirect URIs match exactly
4. **Database**: Verify email_verified column exists

---

## ✅ Checklist

- [ ] Google OAuth configured
- [ ] Gmail App Password created
- [ ] Facebook App created and live
- [ ] Yahoo App created
- [ ] `.env` file updated with all credentials
- [ ] Python packages installed
- [ ] Backend restarted
- [ ] Frontend rebuilt
- [ ] Tested email registration
- [ ] Tested Google login
- [ ] Tested Facebook login
- [ ] Tested Yahoo login

---

**Next Steps**: Once everything is tested and working, we'll add:

- Password reset functionality
- Re-send verification email
- Account deletion
- Social account linking/unlinking

**Ready to implement!** Follow this guide step by step, and your authentication system will be fully functional.