Skip to content

OAUTH_CONFIG_EN.md

Latest commit

 

History

History
227 lines (163 loc) · 6.5 KB

OAUTH_CONFIG_EN.md

File metadata and controls

227 lines (163 loc) · 6.5 KB
Raw

OAuth Third-Party Login Configuration Guide

This document explains how to configure Google and GitHub OAuth login, as well as Cloudflare Turnstile CAPTCHA verification.

Table of Contents

Google OAuth Configuration

Step 1: Create a Google Cloud Project

  1. Visit Google Cloud Console
  2. Click the project selector at the top, then click "New Project"
  3. Enter a project name (e.g., QuantDinger), click "Create"

Step 2: Configure OAuth Consent Screen

  1. In the left menu, select "APIs & Services" → "OAuth consent screen"
  2. Choose user type:
    • External: Allows any Google account to login (recommended)
    • Internal: Only for organization users (requires Google Workspace)
  3. Fill in application information:
    • App name: QuantDinger
    • User support email: Your email
    • Developer contact information: Your email
  4. Click "Save and Continue", skip "Scopes" and "Test users", complete setup

Step 3: Create OAuth 2.0 Client ID

  1. In the left menu, select "APIs & Services" → "Credentials"
  2. Click "+ Create Credentials" → "OAuth client ID"
  3. Select application type: Web application
  4. Enter name: QuantDinger Web Client
  5. Add "Authorized redirect URIs": 
    http://localhost:5000/api/auth/oauth/google/callback

    After deploying to server, add production URI (see below)

  6. Click "Create"
  7. Copy the generated Client ID and Client Secret

Step 4: Configure .env File

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:5000/api/auth/oauth/google/callback

GitHub OAuth Configuration

Step 1: Create GitHub OAuth App

  1. Visit GitHub Developer Settings
  2. Click "OAuth Apps" → "New OAuth App"
  3. Fill in application information:
    • Application name: QuantDinger
    • Homepage URL: http://localhost:8080 (or your domain)
    • Authorization callback URL: 
      http://localhost:5000/api/auth/oauth/github/callback
  4. Click "Register application"

Step 2: Get Credentials

  1. On the application details page, copy the Client ID
  2. Click "Generate a new client secret"
  3. Immediately copy the Client Secret (shown only once)

Step 3: Configure .env File

# GitHub OAuth
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_REDIRECT_URI=http://localhost:5000/api/auth/oauth/github/callback

Cloudflare Turnstile Configuration

Turnstile is a free, privacy-friendly CAPTCHA service provided by Cloudflare to prevent bot attacks.

Step 1: Create Turnstile Widget

  1. Visit Cloudflare Turnstile
  2. Click "Add site"
  3. Fill in information:
    • Site name: QuantDinger
    • Domain: Add your domain (for local development, add localhost)
    • Widget Mode: Select Managed (recommended) or Invisible
  4. Click "Create"

Step 2: Get Keys

After creation, you will see:

  • Site Key: Used by frontend, can be public
  • Secret Key: Used by backend, keep it secret

Step 3: Configure .env File

# Cloudflare Turnstile
TURNSTILE_SITE_KEY=your-site-key
TURNSTILE_SECRET_KEY=your-secret-key

Deployment Configuration

When deploying to a server with a domain name, you need to update the configuration.

Scenario 1: Same Domain for Frontend and Backend (Recommended)

Assuming your domain is yourdomain.com, with frontend and backend deployed under the same domain via nginx reverse proxy:

  • Frontend: https://yourdomain.com
  • Backend API: https://yourdomain.com/api

.env Configuration:

# Frontend URL (redirect after OAuth success)
FRONTEND_URL=https://yourdomain.com

# Google OAuth
GOOGLE_REDIRECT_URI=https://yourdomain.com/api/auth/oauth/google/callback

# GitHub OAuth
GITHUB_REDIRECT_URI=https://yourdomain.com/api/auth/oauth/github/callback

Scenario 2: Separate Domains for Frontend and Backend

Assuming:

  • Frontend: https://yourdomain.com
  • Backend API: https://api.yourdomain.com

.env Configuration:

FRONTEND_URL=https://yourdomain.com

GOOGLE_REDIRECT_URI=https://api.yourdomain.com/api/auth/oauth/google/callback

GITHUB_REDIRECT_URI=https://api.yourdomain.com/api/auth/oauth/github/callback

Update OAuth Provider Settings

After deployment, you also need to update callback URLs in OAuth provider dashboards:

Google Cloud Console:

  1. Go to "Credentials" page
  2. Edit your OAuth client
  3. Add production URL in "Authorized redirect URIs": 
    https://yourdomain.com/api/auth/oauth/google/callback

GitHub Developer Settings:

  1. Edit your OAuth App
  2. Update "Authorization callback URL" to production URL

Turnstile Domain Configuration

In Cloudflare Turnstile dashboard, make sure to add your production domains:

  • yourdomain.com
  • www.yourdomain.com (if used)

FAQ

Q: OAuth login shows "redirect_uri_mismatch" error

A: Callback URL mismatch. Please check:

  1. GOOGLE_REDIRECT_URI or GITHUB_REDIRECT_URI in .env
  2. Callback URL configured in OAuth provider dashboard
  3. Both must match exactly (including http/https, port, path)

Q: Turnstile verification keeps failing

A: Please check:

  1. Are TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY correct?
  2. Is your current domain added to Turnstile's domain list?
  3. For local development, make sure localhost is added

Q: How to disable third-party login?

A: Leave the related configuration empty in .env:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

The system will automatically hide third-party login buttons.

Q: How to disable user registration?

A: Set in .env:

ENABLE_REGISTRATION=false

Q: OAuth login succeeds but cannot redirect back to frontend

A: Please check if FRONTEND_URL is configured correctly, make sure it's the complete frontend page URL (including protocol).

Related Links