QQ 登入是中國大陸用戶體系最龐大的第三方登入方式。本文基於 OAuth 2.0 標準流程,詳細說明從申請應用、配置回調、整合官方 SDK、獲取 Access Token、拉取用戶資訊的完整實作步驟,並提供安全性最佳實踐。
1. 用戶點擊「QQ 登入」 → 導向 QQ 授權頁
https://graph.qq.com/oauth2.0/authorize?
response_type=code&
client_id=YOUR_APP_ID&
redirect_uri=YOUR_CALLBACK_URL&
state=RANDOM_STRING&
scope=get_user_info
2. 用戶授權後,QQ 重導向回調帶 code
YOUR_CALLBACK_URL?code=XXX&state=RANDOM_STRING
3. 後端用 code 換取 Access Token
POST https://graph.qq.com/oauth2.0/token
grant_type=authorization_code&
client_id=YOUR_APP_ID&
client_secret=YOUR_APP_KEY&
code=XXX&
redirect_uri=YOUR_CALLBACK_URL
4. 使用 Access Token 獲取 OpenID
GET https://graph.qq.com/oauth2.0/me?access_token=ACCESS_TOKEN
回傳:callback({"client_id":"APPID","openid":"OPENID"})
5. 使用 Access Token + OpenID 獲取用戶資訊
GET https://graph.qq.com/user/get_user_info
access_token=ACCESS_TOKEN&oauth_consumer_key=APPID&openid=OPENID
https://example.com/callback.php(需 HTTPS、域名備案)vendor/qqconnect/)<?php
// vendor/qqconnect/Recorder.class.php 或 config.php
return [
'app_id' => 'YOUR_APP_ID',
'app_key' => 'YOUR_APP_KEY',
'callback' => 'https://example.com/callback.php',
'scope' => 'get_user_info,add_share', // 申請的權限
'error_display' => true, // 開發環境顯示錯誤
'state' => true, // 啟用 CSRF 保護
];
<?php
// login.php
require_once 'vendor/qqconnect/qqConnectAPI.php';
$qc = new QC(); // SDK 入口類
$loginUrl = $qc->qq_login(); // 內部產生 state 存入 session
echo "
";
<?php
// callback.php
require_once 'vendor/qqconnect/qqConnectAPI.php';
$qc = new QC();
$accessToken = $qc->qq_callback(); // 內部驗證 state、換取 access_token、獲取 openid
if ($accessToken) {
// 登入成功,獲取用戶資訊
$userInfo = $qc->get_user_info();
/*
$userInfo 結構:
[
'ret' => 0,
'msg' => '',
'nickname' => '用戶昵稱',
'figureurl_qq_1' => 'https://.../40.jpg', // 40x40
'figureurl_qq_2' => 'https://.../100.jpg', // 100x100
'gender' => '男',
'province' => '廣東',
'city' => '深圳',
'year' => '1990',
// ...
]
*/
if ($userInfo['ret'] === 0) {
// 這裡綁定/建立本地用戶帳號
$openid = $_SESSION['qq_openid'];
$localUser = bindOrCreateUser($openid, $userInfo);
// 設定登入 Session
$_SESSION['user_id'] = $localUser->id;
header('Location: /dashboard');
exit;
}
}
// 失敗處理
echo "QQ 登入失敗:" . ($userInfo['msg'] ?? '未知錯誤');
function bindOrCreateUser(string $openid, array $qqInfo): User
{
// 1. 查詢是否已綁定
$existing = User::where('qq_openid', $openid)->first();
if ($existing) {
// 更新頭像、暱稱等
$existing->update([
'avatar' => $qqInfo['figureurl_qq_2'],
'nickname' => $qqInfo['nickname'],
'last_login_at' => now(),
]);
return $existing;
}
// 2. 檢查當前是否已登入(合併帳號)
if (auth()->check()) {
$currentUser = auth()->user();
$currentUser->update(['qq_openid' => $openid]);
return $currentUser;
}
// 3. 建立新用戶
return User::create([
'nickname' => $qqInfo['nickname'],
'avatar' => $qqInfo['figureurl_qq_2'],
'qq_openid' => $openid,
'password' => null, // 第三方登入用戶無密碼
'email' => $qqInfo['email'] ?? null, // QQ 可能不提供 email
]);
}
| 風險 | 對策 |
|---|---|
| CSRF 攻擊 | 啟用 state 參數,登入時產生隨機字串存入 Session,回調時驗證 |
| Access Token 洩露 | 僅在 Server-to-Server 請求使用,不傳給前端,儲存於加密 Session/資料庫 |
| 重放攻擊 | code 一次性使用,SDK 會自動處理 |
| OpenID 枚舉 | 不在前端暴露 OpenID,僅後端使用 |
| 帳號劫持 | 綁定時要求驗證手機/郵箱,或要求輸入當前密碼確認 |
| 錯誤代碼/現象 | 原因 | 解決 |
|---|---|---|
| redirect_uri mismatch | 回調網址與後台設定不一致(含 http/https、尾斜線) | 嚴格對齊,含協定、域名、路徑 |
| invalid client | App ID/Key 錯誤、應用未審核通過 | 確認應用狀態為「已上線」 |
| scope not authorized | 用戶未勾選該權限、權限未審核 | 引導用戶重新授權、確認後台權限狀態 |
| get_user_info 返回 ret=-1 | Access Token 過期或無效 | 重新走授權流程獲取新 token |
| 本地開發無法回調 | QQ 要求 HTTPS、備案域名 | 用 ngrok/frp 映射本地 HTTPS、修改 hosts 綁定備案域名 |
QQ 登入整合核心在於:正確配置回調域、妥善保管 App Key、嚴格驗證 state、安全儲存 Access Token/OpenID、合理處理帳號綁定邏輯。使用官方 SDK 可大幅減少手造 HTTP 請求的錯誤。建議將整合邏輯封裝為 SocialiteQQProvider 類別,符合 Laravel Socialite / Symfony KnpU OAuth2Client 介面,便於未來擴充微信、微博、GitHub 等多平台登入。