萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 第三方登入整合:QQ 登入 OAuth 2.0 完整實作流程與 SDK 設定

前言

QQ 登入是中國大陸用戶體系最龐大的第三方登入方式。本文基於 OAuth 2.0 標準流程,詳細說明從申請應用、配置回調、整合官方 SDK、獲取 Access Token、拉取用戶資訊的完整實作步驟,並提供安全性最佳實踐。

一、OAuth 2.0 授權碼模式流程圖解

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

二、前置準備

  1. 註冊開發者帳號:QQ 互聯
  2. 建立網站應用:填寫網站名稱、網址、Logo、驗證網域擁有權
  3. 獲取 App ID & App Key:審核通過後在「應用管理」查看
  4. 設定授權回調域:如 https://example.com/callback.php(需 HTTPS、域名備案)
  5. 下載官方 SDK:PHP SDK,解壓至專案目錄(如 vendor/qqconnect/)

三、SDK 設定檔配置

<?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 保護
];

四、核心實作程式碼

1. 產生授權連結(登入頁)

<?php
// login.php
require_once 'vendor/qqconnect/qqConnectAPI.php';

$qc = new QC(); // SDK 入口類
$loginUrl = $qc->qq_login(); // 內部產生 state 存入 session
echo "\"QQ";

2. 回調處理(callback.php)

<?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'] ?? '未知錯誤');

3. 綁定/建立本地用戶(關鍵邏輯)

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 clientApp ID/Key 錯誤、應用未審核通過確認應用狀態為「已上線」
scope not authorized用戶未勾選該權限、權限未審核引導用戶重新授權、確認後台權限狀態
get_user_info 返回 ret=-1Access Token 過期或無效重新走授權流程獲取新 token
本地開發無法回調QQ 要求 HTTPS、備案域名用 ngrok/frp 映射本地 HTTPS、修改 hosts 綁定備案域名

結語

QQ 登入整合核心在於:正確配置回調域、妥善保管 App Key、嚴格驗證 state、安全儲存 Access Token/OpenID、合理處理帳號綁定邏輯。使用官方 SDK 可大幅減少手造 HTTP 請求的錯誤。建議將整合邏輯封裝為 SocialiteQQProvider 類別,符合 Laravel Socialite / Symfony KnpU OAuth2Client 介面,便於未來擴充微信、微博、GitHub 等多平台登入。

copyright © 萬盛學電腦網 all rights reserved