-
-
Notifications
You must be signed in to change notification settings - Fork 160
Description
🧩 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
.envwithout 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:
-
Go to Google Cloud Console
https://console.cloud.google.com/ -
Create or select a project
-
Navigate to:
APIs & Services → Credentials -
Click Create Credentials → OAuth Client ID
-
Configure the consent screen (if not already done):
-
User Type: External
-
Add your email under Test users
-
-
Create OAuth Client:
-
Application type: Web application
-
Name:
DebateAI Local Dev
-
-
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) -
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:
-
Go to Google Account Security
https://myaccount.google.com/security -
Enable 2-Step Verification
-
Navigate to:
App passwords -
Create a new app password:
-
App: Mail
-
Device: Other (DebateAI)
-
-
Copy the 16-character password
-
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