OAuth 2.0 认证 - Google Sheets API for Laravel

在 OAuth 2.0 认证下，由用户为自己的 Google Sheets 授权访问权限。适合处理用户各自数据的应用。

适用场景

面向用户的应用 —— 用户访问自己的 Google Sheets
多租户应用 —— 不同用户管理各自不同的电子表格
个人数据访问 —— 读写用户个人账号中的表格
桌面 / Web 应用 —— 存在用户交互的场景

前置条件

Google Cloud Console 项目
已启用 Google Sheets API 与 Google Drive API
Laravel Socialite（推荐）

搭建步骤

配置 Google Cloud Console

访问 Google Cloud Console
选择项目或新建项目
进入 APIs & Services > Library
启用以下 API：
- Google Sheets API
- Google Drive API

创建 OAuth 2.0 凭据

进入 APIs & Services > Credentials
点击 Create Credentials > OAuth client ID
配置 OAuth 同意屏幕（仅首次）：
- 用户类型选择 External
- 填写必填项（应用名、支持邮箱、开发者联系方式）
- 添加 scope：https://www.googleapis.com/auth/spreadsheets 与 https://www.googleapis.com/auth/drive
应用类型选择 Web application
添加授权重定向 URI：
- 开发环境: http://localhost:8000/auth/google/callback
- 生产环境: https://yourdomain.com/auth/google/callback
点击 Create
复制 Client ID 与 Client Secret

配置 Laravel 环境

在 .env 中添加：

GOOGLE_CLIENT_ID=your-client-id-here
GOOGLE_CLIENT_SECRET=your-client-secret-here
GOOGLE_REDIRECT=http://localhost:8000/auth/google/callback

更新 config/google.php：

'client_id' => env('GOOGLE_CLIENT_ID', ''),
'client_secret' => env('GOOGLE_CLIENT_SECRET', ''),
'redirect_uri' => env('GOOGLE_REDIRECT', ''),
'scopes' => [
    \Google\Service\Sheets::SPREADSHEETS,
    \Google\Service\Drive::DRIVE,
],
'access_type' => 'offline', // refresh token 必须
'prompt' => 'consent select_account',

安装 Laravel Socialite

composer require laravel/socialite

在 config/services.php 中添加：

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => env('GOOGLE_REDIRECT'),
],

实现认证控制器

// app/Http/Controllers/AuthController.php
<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Laravel\Socialite\Facades\Socialite;

class AuthController extends Controller
{
    public function redirectToGoogle()
    {
        return Socialite::driver('google')
            ->scopes(config('google.scopes'))
            ->with([
                'access_type' => config('google.access_type'),
                'prompt' => config('google.prompt'),
            ])
            ->redirect();
    }

    public function handleGoogleCallback()
    {
        try {
            $googleUser = Socialite::driver('google')->user();
            
            $user = User::updateOrCreate(
                ['email' => $googleUser->email],
                [
                    'name' => $googleUser->name,
                    'email' => $googleUser->email,
                    'google_access_token' => $googleUser->token,
                    'google_refresh_token' => $googleUser->refreshToken,
                    'google_expires_in' => $googleUser->expiresIn,
                    'google_token_created' => now()->timestamp,
                ]
            );

            auth()->login($user);

            return redirect('/dashboard')->with('success', 'Google 认证成功');
        } catch (\Exception $e) {
            return redirect('/login')
                ->with('error', '认证失败: ' . $e->getMessage());
        }
    }

    public function logout(Request $request)
    {
        auth()->logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return redirect('/');
    }
}

添加路由

// routes/web.php
Route::get('/auth/google', [AuthController::class, 'redirectToGoogle'])
    ->name('google.redirect');
Route::get('/auth/google/callback', [AuthController::class, 'handleGoogleCallback'])
    ->name('google.callback');
Route::post('/logout', [AuthController::class, 'logout'])
    ->name('logout');

更新 User 模型

迁移：

// database/migrations/add_google_tokens_to_users_table.php
Schema::table('users', function (Blueprint $table) {
    $table->text('google_access_token')->nullable();
    $table->text('google_refresh_token')->nullable();
    $table->integer('google_expires_in')->nullable();
    $table->integer('google_token_created')->nullable();
});

User 模型：

// app/Models/User.php
protected $fillable = [
    'name',
    'email',
    'password',
    'google_access_token',
    'google_refresh_token',
    'google_expires_in',
    'google_token_created',
];

protected $hidden = [
    'password',
    'remember_token',
    'google_access_token',
    'google_refresh_token',
];

public function getGoogleTokenArray(): array
{
    return [
        'access_token' => $this->google_access_token,
        'refresh_token' => $this->google_refresh_token,
        'expires_in' => $this->google_expires_in,
        'created' => $this->google_token_created,
    ];
}

public function hasValidGoogleToken(): bool
{
    return !empty($this->google_access_token) 
        && !empty($this->google_refresh_token);
}

使用 Sheets

use Revolution\Google\Sheets\Facades\Sheets;

public function getSheetData(Request $request)
{
    $user = $request->user();
    
    if (!$user->hasValidGoogleToken()) {
        return redirect()->route('google.redirect');
    }

    try {
        $token = $user->getGoogleTokenArray();

        $values = Sheets::setAccessToken($token)
            ->spreadsheet('user-spreadsheet-id')
            ->sheet('Sheet1')
            ->all();
            
        return view('sheets.data', compact('values'));
    } catch (\Exception $e) {
        // token 过期时跳转到重新认证
        if (str_contains($e->getMessage(), 'invalid_grant') 
            || str_contains($e->getMessage(), 'unauthorized')) {
            return redirect()->route('google.redirect');
        }

        throw $e;
    }
}

Token 刷新

包会自动处理 token 过期：

$token = [
    'access_token' => $user->google_access_token,
    'refresh_token' => $user->google_refresh_token,
    'expires_in' => $user->google_expires_in,
    'created' => $user->google_token_created,
];

// 如果已过期会自动刷新
Sheets::setAccessToken($token)
    ->spreadsheet('id')
    ->sheet('Sheet1')
    ->all();

// 获取刷新后的 token
$updatedToken = Sheets::getAccessToken();
if ($updatedToken) {
    $user->update([
        'google_access_token' => $updatedToken['access_token'],
        'google_token_created' => time(),
    ]);
}

中间件

强制要求 Google 认证的中间件：

// app/Http/Middleware/RequireGoogleAuth.php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class RequireGoogleAuth
{
    public function handle(Request $request, Closure $next)
    {
        $user = $request->user();

        if (!$user || !$user->hasValidGoogleToken()) {
            if ($request->expectsJson()) {
                return response()->json(
                    ['error' => '需要 Google 认证'], 
                    401
                );
            }

            return redirect()->route('google.redirect');
        }

        return $next($request);
    }
}

安全

1. Token 存储

将 token 安全地保存在数据库中
使用 Laravel 内建加密
不要在客户端暴露 token

2. Scope 管理

只申请最少必要的 scope
遵循最小权限原则
向用户清楚说明所需权限的用途

3. 错误处理

妥善处理过期 token
提供友好的重新认证流程
记录并监控错误

常见问题

常见错误

“redirect_uri_mismatch” 错误

请确认 Google Console 中的重定向 URI 与应用完全一致
检查 http 与 https 的差异
检查末尾是否有斜杠

“invalid_grant” 或 “unauthorized” 错误

token 过期且刷新失败
引导用户重新认证
确认 refresh token 是否存在

“access_denied” 错误

用户拒绝了权限授予
用合适的提示进行处理
提供重新尝试授权的选项

测试路由

Route::get('/test-oauth', function (Request $request) {
    $user = $request->user();
    
    if (!$user->hasValidGoogleToken()) {
        return '没有 Google token。'
            . '<a href="' . route('google.redirect') . '">'
            . '进行认证</a>';
    }
    
    try {
        $token = $user->getGoogleTokenArray();
        $sheets = Sheets::setAccessToken($token)->spreadsheetList();
        
        return 'OAuth 正常工作！电子表格数量: ' 
            . count($sheets);
    } catch (\Exception $e) {
        return 'OAuth 错误: ' . $e->getMessage();
    }
})->middleware('auth');

​适用场景

​前置条件

​搭建步骤

​Token 刷新

​中间件

​安全

​1. Token 存储

​2. Scope 管理

​3. 错误处理

​常见问题

​常见错误

​测试路由