TIANHE
445e7ac290
- Fix token missing issue after email code registration/login - Add last login time update for code-based login - Support email login in addition to username login - Fix password login for code-registered users (allow setting password) - Fix referral code parameter passing from URL hash - Add email column to user management table - Improve profile page layout (align card heights, reorganize layout) - Add i18n support for Register Bonus, Referral Bonus, Code Lock Minutes, Code Max Attempts - Fix billing service add_credits to support reference_id parameter - Update password handling documentation
228 lines
6.5 KiB
Markdown
228 lines
6.5 KiB
Markdown
# 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](#google-oauth-configuration)
|
|
- [GitHub OAuth Configuration](#github-oauth-configuration)
|
|
- [Cloudflare Turnstile Configuration](#cloudflare-turnstile-configuration)
|
|
- [Deployment Configuration](#deployment-configuration)
|
|
- [FAQ](#faq)
|
|
|
|
---
|
|
|
|
## Google OAuth Configuration
|
|
|
|
### Step 1: Create a Google Cloud Project
|
|
|
|
1. Visit [Google Cloud Console](https://console.cloud.google.com/)
|
|
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
|
|
|
|
```bash
|
|
# 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](https://github.com/settings/developers)
|
|
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
|
|
|
|
```bash
|
|
# 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](https://dash.cloudflare.com/?to=/:account/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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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
|
|
|
|
- [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
|
|
- [GitHub Developer Settings](https://github.com/settings/developers)
|
|
- [Cloudflare Turnstile](https://dash.cloudflare.com/?to=/:account/turnstile)
|