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'),
],

實作驗證 Controller

// 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 模型

Migration:

// 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,
];

// 過期時自動 refresh
Sheets::setAccessToken($token)
    ->spreadsheet('id')
    ->sheet('Sheet1')
    ->all();

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

Middleware

要求 Google 驗證的 middleware:

// 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 的 redirect URI 與應用程式完全相符
確認 http vs https 差異
確認結尾斜線

「invalid_grant」或「unauthorized」錯誤

token 過期且 refresh 失敗
要求使用者重新驗證
確認 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');

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

OAuth 2.0 驗證 - Google Sheets API for Laravel

適用場景

前置條件

設定

Token 更新

Middleware

安全性

1. Token 儲存

2. Scope 管理

3. 錯誤處理

疑難排解

常見錯誤

測試路由

​適用場景

​前置條件

​設定

​Token 更新

​Middleware

​安全性

​1. Token 儲存

​2. Scope 管理

​3. 錯誤處理

​疑難排解

​常見錯誤

​測試路由

適用場景

前置條件

設定

Token 更新

Middleware

安全性

1. Token 儲存

2. Scope 管理

3. 錯誤處理

疑難排解

常見錯誤

測試路由