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
2. Gmail SMTP Setup
3. Facebook OAuth Setup
4. Yahoo OAuth Setup
5. Backend Configuration
6. Testing the Implementation

---

1. Google OAuth Setup

Step 1.1: Create Google Cloud Project

1. Go to Google Cloud Console
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
   • 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
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

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:

# 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

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

   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.