Skip to content

Docs Update Needed: Clear Google OAuth & Email Setup Guide #211

@Cubix33

Description

@Cubix33

🧩 Problem

Several contributors face repeated authentication issues (Google Sign-In errors, invalid client, blocked origin, email verification failures) due to unclear or incomplete setup instructions in the current documentation.

The existing docs assume prior OAuth knowledge and do not explain:

  • How to create a Google OAuth Client ID

  • How to correctly configure Authorized JavaScript Origins

  • That the OAuth Client ID should be added to the frontend .env without quotes

  • How to generate a Gmail App Password for SMTP email verification

This leads to errors such as:

  • Error 401: invalid_client

  • The given origin is not allowed for the given client ID

  • 535 5.7.8 Username and Password not accepted

  • Email verification failures during sign-up


✅ Proposed Documentation Improvements

1️⃣ Add a Dedicated “Google OAuth Setup” Section

Step-by-step guide to create OAuth Client ID:

  1. Go to Google Cloud Console
    https://console.cloud.google.com/

  2. Create or select a project

  3. Navigate to:

    APIs & Services → Credentials
  4. Click Create Credentials → OAuth Client ID

  5. Configure the consent screen (if not already done):

    • User Type: External

    • Add your email under Test users

  6. Create OAuth Client:

    • Application type: Web application

    • Name: DebateAI Local Dev

  7. Add Authorized JavaScript Origins:

    http://localhost:5173 http://127.0.0.1:5173 http://localhost:1313 http://127.0.0.1:1313

    ⚠️ These must match the exact frontend URL (protocol + host + port)

  8. Save and copy the Client ID


2️⃣ Clarify Frontend .env Configuration (Important!)

Update frontend docs to explicitly state:

VITE_BASE_URL=http://localhost:1313 VITE_GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID_HERE

Do NOT wrap values in quotes
❗ Restart the frontend after changes


3️⃣ Add Gmail App Password Setup Guide (for Email Verification)

Why this is needed

Gmail does not allow normal account passwords for SMTP. An App Password is required.

Steps:

  1. Go to Google Account Security
    https://myaccount.google.com/security

  2. Enable 2-Step Verification

  3. Navigate to:

    App passwords
  4. Create a new app password:

    • App: Mail

    • Device: Other (DebateAI)

  5. Copy the 16-character password

  6. Update backend config.prod.yml:

smtp: host: "smtp.gmail.com" port: 587 username: "your-email@gmail.com" password: "your-app-password-here" senderEmail: "your-email@gmail.com"

❗ Do NOT use your normal Gmail password
❗ Do NOT commit this file


Benefits:

  • Reduces onboarding friction

  • Prevents repeated OAuth-related issues

  • Makes setup beginner-friendly

  • Improves contributor experience for GSoC & OSS contributors

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions