OAuth 第三方登入模組

功能說明

介面字首統一為 http(s)://<your-domain>

生產環境應使用 HTTPS 以保證認證令牌。 HTTP 僅建議用於開發環境。

支援 GitHub、OIDC、LinuxDO、微信、Telegram 等多種 OAuth 登入方式。實現 CSRF 防護和會話管理，支援賬戶繫結和自動註冊。前端透過重定向方式處理 OAuth 流程。

🔐 無需鑑權

GitHub OAuth 跳轉

介面名稱：GitHub OAuth 跳轉
HTTP 方法：GET
路徑：/api/oauth/github
鑑權要求：公開
功能簡介：處理 GitHub OAuth 回撥，完成使用者登入或賬戶繫結

💡 請求示例：

_// 前端透過重定向方式呼叫，通常由GitHub OAuth授權後自動回撥  _window.location.href = `https://github.com/login/oauth/authorize?client_id=${github_client_id}&state=${state}&scope=user:email`;

✅ 成功響應示例：

{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "github_user",
      "display_name": "GitHub User",
      "email": "user@example.com"
    }
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "管理員未開啟透過 GitHub 登入以及註冊"
}

🧾 欄位說明：

code （字串）: GitHub OAuth 授權碼，由 GitHub 回撥時提供
state （字串）: 防 CSRF 狀態碼，必須與 session 中儲存的一致

OIDC 通用 OAuth 跳轉

介面名稱：OIDC 通用 OAuth 跳轉
HTTP 方法：GET
路徑：/api/oauth/oidc
鑑權要求：公開
功能簡介：處理 OIDC OAuth 回撥，支援通用 OpenID Connect 協議登入

💡 請求示例：

_// 前端透過重定向方式呼叫  _
const url = new URL(auth_url);
url.searchParams.set('client_id', client_id);
url.searchParams.set('redirect_uri', `${window.location.origin}/oauth/oidc`);
url.searchParams.set('response_type', 'code');
url.searchParams.set('scope', 'openid profile email');
url.searchParams.set('state', state);
window.location.href = url.toString();

✅ 成功響應示例：

{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "oidc_user",
      "email": "user@example.com"
    }
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "OIDC 獲取使用者資訊失敗！請檢查設定！"
}

🧾 欄位說明：

code （字串）: OIDC 授權碼
state （字串）: 防 CSRF 狀態碼

LinuxDo OAuth 跳轉

介面名稱：LinuxDo OAuth 跳轉
HTTP 方法：GET
路徑：/api/oauth/linuxdo
鑑權要求：公開
功能簡介：處理 LinuxDo OAuth 回撥，支援透過 LinuxDo 社群賬戶登入

💡 請求示例：

_// 前端透過重定向方式呼叫  _
window.location.href = `https://connect.linux.do/oauth2/authorize?response_type=code&client_id=${linuxdo_client_id}&state=${state}`;

✅ 成功響應示例：

{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "linuxdo_user",
      "display_name": "LinuxDo User"
    }
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "管理員關閉了新使用者註冊"
}

🧾 欄位說明：

code （字串）: LinuxDo OAuth 授權碼
state （字串）: 防 CSRF 狀態碼
error （字串）: 可選，OAuth 錯誤碼
error_description （字串）: 可選，錯誤描述

微信掃碼登入跳轉

介面名稱：微信掃碼登入跳轉
HTTP 方法：GET
路徑：/api/oauth/wechat
鑑權要求：公開
功能簡介：處理微信掃碼登入，透過驗證碼完成登入流程

💡 請求示例：

const response = await fetch(`/api/oauth/wechat?code=${wechat_verification_code}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "wechat_user",
      "wechat_id": "wechat_openid"
    }
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "驗證碼無效或已過期"
}

🧾 欄位說明：

code （字串）: 微信掃碼獲得的驗證碼

微信賬戶繫結

介面名稱：微信賬戶繫結
HTTP 方法：GET
路徑：/api/oauth/wechat/bind
鑑權要求：公開
功能簡介：將微信賬戶繫結到現有使用者賬戶

💡 請求示例：

const response = await fetch(`/api/oauth/wechat/bind?code=${wechat_verification_code}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "微信賬戶繫結成功！"
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "驗證碼無效或該微信賬戶已被繫結"
}

🧾 欄位說明：

code （字串）: 微信掃碼獲得的驗證碼

郵箱繫結

介面名稱：郵箱繫結
HTTP 方法：GET
路徑：/api/oauth/email/bind
鑑權要求：公開
功能簡介：透過郵箱驗證碼繫結郵箱到使用者賬戶

💡 請求示例：

const response = await fetch(`/api/oauth/email/bind?email=${email}&code=${email_verification_code}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "郵箱賬戶繫結成功！"
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "驗證碼無效或郵箱已被使用"
}

🧾 欄位說明：

email （字串）: 要繫結的郵箱地址
code （字串）: 郵箱驗證碼

Telegram 登入

介面名稱：Telegram 登入
HTTP 方法：GET
路徑：/api/oauth/telegram/login
鑑權要求：公開
功能簡介：透過 Telegram Widget 完成使用者登入

💡 請求示例：

const params = {
  id: telegram_user_id,
  first_name: "John",
  last_name: "Doe",
  username: "johndoe",
  photo_url: "https://...",
  auth_date: 1640995200,
  hash: "telegram_hash"
};
const query = new URLSearchParams(params).toString();
const response = await fetch(`/api/oauth/telegram/login?${query}`, {
  method: 'GET'
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "登入成功",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "telegram_user",
      "telegram_id": "123456789"
    }
  }
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "Telegram驗證失敗"
}

🧾 欄位說明：

id （字串）: Telegram 使用者 ID
first_name （字串）: 使用者名稱字
last_name （字串）: 使用者姓氏，可選
username （字串）: Telegram 使用者名稱，可選
photo_url （字串）: 頭像 URL，可選
auth_date （數字）: 認證時間戳
hash （字串）: Telegram 驗證雜湊

Telegram 賬戶繫結

介面名稱：Telegram 賬戶繫結
HTTP 方法：GET
路徑：/api/oauth/telegram/bind
鑑權要求：公開
功能簡介：將 Telegram 賬戶繫結到現有使用者賬戶

💡 請求示例：

// 透過TelegramLoginButton元件自動處理引數
// 引數格式與Telegram登入相同
const response = await fetch('/api/oauth/telegram/bind', {
  method: 'GET',
  params: telegram_auth_params
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "Telegram賬戶繫結成功！"
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "該Telegram賬戶已被繫結"
}

🧾 欄位說明：

引數格式與 Telegram 登入介面相同

獲取隨機 state（防 CSRF）

介面名稱：獲取隨機 state
HTTP 方法：GET
路徑：/api/oauth/state
鑑權要求：公開
功能簡介：生成隨機 state 引數用於 OAuth 流程的 CSRF 防護

💡 請求示例：

let path = '/api/oauth/state';
let affCode = localStorage.getItem('aff');
if (affCode && affCode.length > 0) {
  path += `?aff=${affCode}`;
}
const response = await fetch(path, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ 成功響應示例：

{
  "success": true,
  "message": "",
  "data": "random_state_string_12chars"
}

❗ 失敗響應示例：

{
  "success": false,
  "message": "生成state失敗"
}

🧾 欄位說明：

aff （字串）: 可選，推薦碼引數，用於記錄使用者來源
data （字串）: 返回的隨機 state 字串，長度為 12 位

目錄