Google OAuth2 登录实现：正确管理用户访问令牌与刷新令牌

本文详解 php 中 google oauth2 登录的令牌管理机制，指出常见误区（如错误存储访问令牌），强调应仅持久化刷新令牌、将访问令牌存于加密会话中，并提供安全登出方案。

在基于 Google OAuth2 的网站登录系统中，理解访问令牌（Access Token）与刷新令牌（Refresh Token）的职责边界，是避免 401 Unauthorized 错误和用户体验中断的关键。正如问题中所见，Fatal error 的根本原因并非 Google API 调用失败，而是逻辑层面的令牌误用：将已失效甚至已被主动吊销（revoke）的访问令牌从数据库读出并直接复用。

? 核心概念澄清

• 访问令牌（Access Token）是用户级、短期、一次性凭证：它由 Google 颁发，绑定具体用户身份（sub）、客户端（client_id）及作用域（scope），默认有效期为 3600 秒（1 小时），且不可刷新自身。一旦过期或被吊销（如调用 revokeToken()），该令牌立即永久失效。
• 刷新令牌（Refresh Token）是用户级、长期、高权限凭证：首次授权成功后（需 setAccessType('offline') + setPrompt('consent')），Google 会返回一个刷新令牌（仅首次授权时下发一次）。它可用于在访问令牌过期后，静默获取新的有效访问令牌，无需用户再次交互。应安全持久化存储（如数据库加密字段），并严格保护。

✅ 正确实践：每个用户对应唯一的一组令牌对（1 个 Refresh Token + 当前有效的 Access Token），而非全站共用一个“应用级令牌”。

? 正确的登录流程（PHP 实现）

以下代码重构了原始逻辑，遵循最佳实践：

setAuthConfig($_SERVER['DOCUMENT_ROOT'] . '/login/credentials.json');
$client->setAccessType('offline');      // 必须启用离线访问以获取 refresh_token
$client->setPrompt('consent');          // 确保首次获取 refresh_token
$client->addScope(['email', 'profile']);

$dbx = new db();

// 1. 优先尝试从 SESSION 获取有效 Access Token
$accessToken = $_SESSION['google_access_token'] ?? null;
if ($accessToken && !$client->isAccessTokenExpired($accessToken)) {
    $client->setAccessToken($accessToken);
} else {
    // 2. Session 无效 → 尝试用 Refresh Token 换新 Access Token
    $refreshToken = $dbx->get_refresh_token(); // 仅存储 refresh_token！
    if ($refreshToken) {
        $client->fetchAccessTokenWithRefreshToken($refreshToken);
        $newToken = $client->getAccessToken();
        $_SESSION['google_access_token'] = $newToken;
        // 可选：更新 Access Token 的本地缓存（非必需，因 session 已存）
    } elseif (isset($_GET['code'])) {
        // 3. 无 Refresh Token 且有授权码 → 完成首次授权
        $tokenResponse = $client->fetchAccessTokenWithAuthCode($_GET['code']);
        $client->setAccessToken($tokenResponse);
        $_SESSION['google_access_token'] = $tokenResponse;
        // ✅ 仅在此处持久化 Refresh Token（首次且唯一机会）
        if (isset($tokenResponse['refresh_token'])) {
            $dbx->set_refresh_token($tokenResponse['refresh_token']);
        }
    } else {
        // 4. 未授权 → 重定向至 Google 登录页
        header('Location: ' . $client->createAuthUrl());
        exit;
    }
}

// 5. 使用有效 AccessToken 调用 API
$service = new Google_Service_Oauth2($client);
$userdata = $service->userinfo->get();

// ✅ 建议：将用户基础信息也存入 session，减少后续 API 调用
$_SESSION['user_profile'] = [
    'id' => $userdata->getId(),
    'email' => $userdata->getEmail(),
    'name' => $userdata->getName(),
    'picture' => $userdata->getPicture()
];

? 安全登出：不调用 Google 吊销，只清理本地状态

原始登出脚本调用 $client->revokeToken($accessToken) 是严重错误——它会全局注销用户在所有第三方应用中的 Google 会话，损害用户体验且违反 OAuth 最小权限原则。

✅ 正确登出只需三步：

1. 销毁当前会话：session_destroy() 或 $_SESSION = [];
2. 清除本地持久化凭证：删除数据库中该用户的 refresh_token；
3. 可选：前端跳转至 Google 注销页（仅 UI 提示，非必需）：

   // 仅用于清除 Google 自身的登录态（非必须，且需注意 UX）
   $logoutUrl = 'https://accounts.google.com/logout';
   header("Location: $logoutUrl");

⚠️ 关键注意事项总结

• 绝不持久化 Access Token：它短暂、易失效、无需长期保存。Session 是其理想载体。
• 务必加密存储 Refresh Token：数据库字段应使用 AES-256 等强加密，密钥不得硬编码。
• 始终校验 isAccessTokenExpired()：传入具体 token 数组，而非依赖 $client->isAccessTokenExpired()（它检查内部状态，可能不准）。
• 处理令牌刷新失败：若 fetchAccessTokenWithRefreshToken() 返回错误（如 invalid_grant），说明 Refresh Token 已失效（用户手动撤销、超期未用等），需引导用户重新登录。
• 启用 HTTPS：OAuth 流程全程必须在 TLS 加密下进行，否则令牌易被劫持。

通过厘清令牌生命周期与职责分离，你的登录系统将兼具安全性、健壮性与良好用户体验——不再因一个过期的字符串而崩溃。