Mô-đun đăng nhập bên thứ ba OAuth

Mô tả tính năng

Tiền tố giao diện thống nhất là http(s)://<your-domain>

Nên sử dụng HTTPS trong môi trường sản xuất để bảo mật mã thông báo xác thực. HTTP chỉ được khuyến nghị cho môi trường phát triển.

Hỗ trợ nhiều phương thức đăng nhập OAuth khác nhau như GitHub, OIDC, LinuxDO, WeChat và Telegram. Triển khai bảo vệ CSRF và quản lý phiên, hỗ trợ liên kết tài khoản và đăng ký tự động. Giao diện người dùng xử lý quy trình OAuth thông qua chuyển hướng.

🔐 Không cần xác thực

Chuyển hướng GitHub OAuth

Tên giao diện:Chuyển hướng GitHub OAuth
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/github
Yêu cầu xác thực:Công khai
Mô tả chức năng:Xử lý lệnh gọi lại GitHub OAuth để hoàn tất đăng nhập người dùng hoặc liên kết tài khoản

💡 Ví dụ yêu cầu:

_// The front end is called through redirection，usually composed ofGitHub OAuthAutomatic callback after authorization  _window.location.href = `https://github.com/login/oauth/authorize?client_id=${github_client_id}&state=${state}&scope=user:email`;

✅ Ví dụ phản hồi thành công:

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

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The administrator has not enabled the pass GitHub Log in and register"
}

🧾 Mô tả trường:

code (String): Mã ủy quyền GitHub OAuth, được GitHub cung cấp khi gọi lại
state (String): Mã trạng thái Anti-CSRF, phải khớp với mã được lưu trong phiên

Chuyển hướng OIDC chung OAuth

Tên giao diện:Chuyển hướng OIDC chung OAuth
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/oidc
Yêu cầu xác thực:Công khai
Mô tả chức năng:Xử lý lệnh gọi lại OIDC OAuth, hỗ trợ đăng nhập giao thức OpenID Connect chung

💡 Ví dụ yêu cầu:

_// The front end is called through redirection  _
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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "oidc_user",
      "email": "user@example.com"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "OIDC Failed to obtain user information！Please check settings！"
}

🧾 Mô tả trường:

code (String): mã ủy quyền OIDC
state (String): Mã trạng thái anti-CSRF

Chuyển hướng LinuxDo OAuth

Tên giao diện:Chuyển hướng LinuxDo OAuth
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/linuxdo
Yêu cầu xác thực:Công khai
Mô tả chức năng:Xử lý lệnh gọi lại LinuxDo OAuth, hỗ trợ đăng nhập qua tài khoản cộng đồng LinuxDo

💡 Ví dụ yêu cầu:

_// The front end is called through redirection  _
window.location.href = `https://connect.linux.do/oauth2/authorize?response_type=code&client_id=${linuxdo_client_id}&state=${state}`;

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "linuxdo_user",
      "display_name": "LinuxDo User"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The administrator has closed new user registration"
}

🧾 Mô tả trường:

code (String): Mã ủy quyền LinuxDo OAuth
state (String): Mã trạng thái anti-CSRF
error (String): Tùy chọn, mã lỗi OAuth
error_description (String): Tùy chọn, mô tả lỗi

Chuyển hướng đăng nhập mã QR WeChat

Tên giao diện:Chuyển hướng đăng nhập mã QR WeChat
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/wechat
Yêu cầu xác thực:Công khai
Mô tả chức năng:Xử lý đăng nhập bằng mã QR WeChat, hoàn tất quá trình đăng nhập thông qua mã xác minh

💡 Ví dụ yêu cầu:

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

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "wechat_user",
      "wechat_id": "wechat_openid"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "Verification code is invalid or expired"
}

🧾 Mô tả trường:

code (String): Mã xác minh thu được từ quá trình quét QR của WeChat

Ràng buộc tài khoản WeChat

Tên giao diện:Ràng buộc tài khoản WeChat
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/wechat/bind
Yêu cầu xác thực:Công khai
Mô tả chức năng:Liên kết tài khoản WeChat với tài khoản người dùng hiện có

💡 Ví dụ yêu cầu:

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

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "WeChat account bound successfully！"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The verification code is invalid or the WeChat account has been bound"
}

🧾 Mô tả trường:

code (String): Mã xác minh thu được từ quá trình quét QR của WeChat

Ràng buộc email

Tên giao diện:Ràng buộc email
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/email/bind
Yêu cầu xác thực:Công khai
Mô tả chức năng:Liên kết địa chỉ email với tài khoản người dùng thông qua mã xác minh email

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Email account bound successfully！"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The verification code is invalid or the email address has been used"
}

🧾 Mô tả trường:

email (String): Địa chỉ email cần ràng buộc
code (String): Mã xác minh email

Đăng nhập Telegram

Tên giao diện:Đăng nhập Telegram
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/telegram/login
Yêu cầu xác thực:Công khai
Mô tả chức năng:Hoàn tất đăng nhập của người dùng thông qua Widget Telegram

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "telegram_user",
      "telegram_id": "123456789"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "TelegramAuthentication failed"
}

🧾 Mô tả trường:

id (Chuỗi): ID người dùng Telegram
first_name (Chuỗi): Tên người dùng
last_name (String): Họ của người dùng, tùy chọn
username (Chuỗi): Tên người dùng Telegram, tùy chọn
photo_url (Chuỗi): URL Avatar, tùy chọn
auth_date (Number): Dấu thời gian xác thực
hash (String): Băm xác minh Telegram

Ràng buộc tài khoản Telegram

Tên giao diện:Ràng buộc tài khoản Telegram
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/telegram/bind
Yêu cầu xác thực:Công khai
Mô tả chức năng:Liên kết tài khoản Telegram với tài khoản người dùng hiện có

💡 Ví dụ yêu cầu:

// passTelegramLoginButtonComponent automatically handles parameters
// The parameter format is the same asTelegramLogin same
const response = await fetch('/api/oauth/telegram/bind', {
  method: 'GET',
  params: telegram_auth_params
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "TelegramAccount binding successful！"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "ShouldTelegramAccount has been bound"
}

🧾 Mô tả trường:

Định dạng tham số giống với giao diện đăng nhập Telegram

Nhận trạng thái ngẫu nhiên (Anti-CSRF)

Tên giao diện:Nhận trạng thái ngẫu nhiên
Phương thức HTTP: NHẬN
Đường dẫn:/api/oauth/state
Yêu cầu xác thực:Công khai
Mô tả chức năng:Tạo tham số trạng thái ngẫu nhiên để bảo vệ CSRF trong luồng OAuth

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

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

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "generatestatefail"
}

🧾 Mô tả trường:

aff (String): Tùy chọn, tham số mã giới thiệu, dùng để ghi nguồn người dùng
data (String): Chuỗi trạng thái ngẫu nhiên được trả về, dài 12 ký tự

Mục lục