Google Calendar PHP API空令牌问题：Web应用授权后无法获取有效令牌

我之前在把Google Calendar API从CLI迁移到Web应用时，也踩过一模一样的令牌获取坑！CLI的quickstart能跑通，但Web环境下的OAuth流程有几个关键细节容易出错，咱们一步步来排查解决：

1. 确认你用的是Web应用类型的OAuth凭据 #

别小看这个凭据类型，CLI用的「桌面应用」凭据和Web应用的凭据完全是两回事：

• 去Google Cloud控制台重新创建一个Web应用类型的凭据
• 把你的回调URL（用户同意后跳转的地址）精确填进去——连http/https、端口号都不能错，比如https://your-app.com/callback和http://your-app.com/callback会被当成两个不同地址，直接导致令牌请求失败

2. 检查令牌请求的参数与请求方式 #

拿到GET['code']后，请求令牌必须满足这些要求：

• 用POST请求发送到https://oauth2.googleapis.com/token
• 必须包含这些参数：
  • client_id：Web应用凭据的ID
  • client_secret：Web应用凭据的密钥
  • code：回调中拿到的授权码
  • redirect_uri：和凭据里配置的完全一致
  • grant_type=authorization_code（固定值）

如果用Google官方的PHP客户端库，直接用fetchAccessTokenWithAuthCode()方法会自动处理这些细节，但要确保客户端对象配置正确。

3. 必须添加CSRF状态验证 #

Web应用里OAuth流程必须做state参数验证，否则不仅有安全风险，还可能被Google拒绝令牌请求：

• 跳转授权页前，生成一个随机的state值存在会话中（比如$_SESSION['oauth_state'] = bin2hex(random_bytes(16))）
• 把这个state附加到授权URL里一起发给用户
• 回调时验证返回的$_GET['state']和会话中的值是否一致，不一致直接终止流程

4. 调整Google客户端库的配置细节 #

和CLI模式的配置差异要注意：

session_start();

$client = new Google_Client();
// 加载Web应用的凭据文件，不是CLI的那个
$client->setAuthConfig('web-credentials.json');
// 设置和凭据中一致的回调地址
$client->setRedirectUri('https://your-domain.com/callback.php');
// 添加需要的日历权限，比如创建事件用CALENDAR_EVENTS
$client->addScope(Google_Service_Calendar::CALENDAR_EVENTS);
// Web应用一般用online模式，不需要离线访问令牌的话不用改
$client->setAccessType('online');
// 强制用户选择账号并确认权限，避免缓存导致的问题
$client->setPrompt('select_account consent');

5. 错误排查技巧 #

如果令牌请求失败，一定要打印出返回的错误信息：

$token = $client->fetchAccessTokenWithAuthCode($_GET['code']);
if (isset($token['error'])) {
    die('令牌获取失败：' . $token['error_description']);
}

常见错误对应的原因：

• invalid_grant：授权码过期（code只有10分钟有效期）或redirect_uri不匹配
• invalid_client：client_id或client_secret填写错误
• access_denied：用户拒绝了权限请求

完整回调流程示例 #

session_start();

require __DIR__ . '/vendor/autoload.php';

$client = new Google_Client();
$client->setAuthConfig('web-credentials.json');
$client->setRedirectUri('https://your-domain.com/callback.php');
$client->addScope(Google_Service_Calendar::CALENDAR_EVENTS);
$client->setAccessType('online');
$client->setPrompt('select_account consent');

// 处理授权回调
if (isset($_GET['code'])) {
    // 验证CSRF状态
    if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['oauth_state']) {
        die('无效的状态参数，可能存在CSRF攻击');
    }
    unset($_SESSION['oauth_state']);

    // 获取访问令牌
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);
    if (isset($token['error'])) {
        die('令牌获取失败：' . $token['error_description']);
    }

    // 把令牌保存到会话（或数据库，根据需求）
    $_SESSION['access_token'] = $token;

    // 跳转到添加日历事件的页面
    header('Location: add-calendar-event.php');
    exit;
} else {
    // 生成CSRF状态并跳转授权页
    $state = bin2hex(random_bytes(16));
    $_SESSION['oauth_state'] = $state;
    $authUrl = $client->createAuthUrl() . '&state=' . $state;
    header('Location: ' . $authUrl);
    exit;
}

内容的提问来源于stack exchange，提问作者MagicalMidge