在Laravel 11+Sanctum中集成Google OAuth的技术求助

我之前在项目里实现过Google OAuth和Sanctum的整合，下面是覆盖你需求的详细步骤、代码示例和避坑要点：

一、配置Google OAuth（Laravel 11） #

1. Google开发者控制台准备 #

• 登录Google开发者控制台，创建新项目，启用「Google+ API」（或直接搜索OAuth 2.0）
• 创建OAuth客户端ID，应用类型选「Web应用」，添加回调URL：http://your-domain.com/auth/google/callback（本地开发用http://localhost:8000/auth/google/callback）
• 记录生成的客户端ID和客户端密钥

2. Laravel项目配置 #

• 安装Socialite（Laravel官方OAuth工具）：

  composer require laravel/socialite
  

• 在.env文件添加配置：

  GOOGLE_CLIENT_ID=你的Google客户端ID
  GOOGLE_CLIENT_SECRET=你的Google客户端密钥
  GOOGLE_REDIRECT=http://your-domain.com/auth/google/callback
  

• 编辑config/services.php，添加Google配置：

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

3. 登录与回调路由 #

在routes/web.php中添加路由：

use Laravel\Socialite\Facades\Socialite;
use App\Models\User;
use Illuminate\Support\Facades\Auth;

// 跳转至Google登录页
Route::get('/auth/google', function () {
    return Socialite::driver('google')->redirect();
});

// Google登录回调处理
Route::get('/auth/google/callback', function () {
    // 获取Google用户信息
    $googleUser = Socialite::driver('google')->user();

    // 查找或创建本地用户（通过google_id关联）
    $user = User::updateOrCreate(
        ['google_id' => $googleUser->id],
        [
            'name' => $googleUser->name,
            'email' => $googleUser->email,
            'email_verified_at' => now(), // Google已验证邮箱，直接标记
        ]
    );

    // 登录用户（创建Web会话，可选）
    Auth::login($user);

    // 生成Sanctum API令牌
    $token = $user->createToken('google-oauth-token')->plainTextToken;

    // 返回令牌给前端（根据你的前端架构，可返回JSON或重定向携带令牌）
    return response()->json([
        'token' => $token,
        'user' => $user->only('id', 'name', 'email')
    ]);
});

二、集成Sanctum处理API令牌 #

1. 安装与配置Sanctum #

• 安装Sanctum：

  composer require laravel/sanctum
  php artisan sanctum:install
  

• 编辑config/auth.php，将API guard的驱动设置为sanctum：

  'guards' => [
      'web' => [
          'driver' => 'session',
          'provider' => 'users',
      ],
      'api' => [
          'driver' => 'sanctum',
          'provider' => 'users',
          'hash' => false,
      ],
  ],
  

2. 用户模型配置 #

在App\Models\User中添加HasApiTokens trait：

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

    // 允许批量赋值的字段
    protected $fillable = [
        'name',
        'email',
        'google_id',
    ];
}

关键说明 #

Google OAuth令牌仅用于身份验证环节，我们不会直接用它作为API请求凭证。而是在用户通过Google认证后，由Sanctum颁发专属的API令牌——这样可以利用Sanctum的令牌管理功能（如撤销、权限控制、有效期设置），比直接使用Google令牌更灵活安全。

三、安全会话与API请求处理 #

1. 前端请求处理 #

• 用户点击登录按钮后，跳转至/auth/google完成Google认证
• 回调获取到Sanctum令牌后，将其存储在HttpOnly Cookie中（比localStorage更安全，防止XSS攻击）
• 后续API请求在请求头中携带令牌：

  fetch('/api/user', {
      headers: {
          'Authorization': `Bearer ${token}`
      }
  })
  

2. 路由保护 #

• Web路由：使用auth中间件保护需要登录的页面：

  Route::middleware('auth')->group(function () {
      Route::get('/dashboard', function () {
          return view('dashboard');
      });
  });
  

• API路由：使用auth:sanctum中间件保护API接口：

  use Illuminate\Http\Request;
  
  Route::middleware('auth:sanctum')->group(function () {
      Route::get('/api/user', function (Request $request) {
          return $request->user();
      });
  
      // 其他需要认证的API接口
  });
  

3. 注销逻辑 #

添加注销路由，同时销毁Sanctum令牌和Google会话：

Route::post('/logout', function (Request $request) {
    // 销毁当前用户的所有Sanctum令牌
    $request->user()->tokens()->delete();

    // 退出Web会话
    Auth::logout();

    // 跳转至Google注销页面（可选，清理Google端会话）
    return redirect('https://accounts.google.com/Logout');
})->middleware('auth');

最佳实践与避坑要点 #

• 不要混用令牌：永远不要用Google OAuth令牌作为API请求凭证，它的有效期短且无法自定义管理，Sanctum令牌才是API的标准凭证
• 回调URL严格匹配：Google控制台的回调URL必须和项目中的完全一致，包括http/https、端口号，本地开发建议用Ngrok生成HTTPS链接避免Google的安全限制
• 令牌权限控制：生成Sanctum令牌时可添加权限能力，实现细粒度控制：

  $token = $user->createToken('google-oauth-token', ['read:posts', 'write:posts'])->plainTextToken;
  

• 邮箱验证：Google返回的邮箱已经过验证，直接设置email_verified_at即可，无需再发验证邮件
• 安全存储令牌：优先使用HttpOnly Cookie存储Sanctum令牌，避免XSS攻击窃取令牌

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