Laravel 11 集成 Passport 实现 OAuth2.0 第三方登录

核心概念

1. Passport：Laravel 官方 OAuth2 服务器包，提供完整的 OAuth2 协议实现
2. OAuth2 流程：
   • 第三方应用请求授权
   • 用户登录并授权
   • 返回授权码 (Authorization Code)
   • 用授权码换取访问令牌 (Access Token)

实现步骤

---

1. 安装依赖

composer require laravel/passport
php artisan migrate  # 创建OAuth相关数据表
php artisan passport:install  # 生成加密密钥

---

2. 配置模型与守卫

修改 App\Models\User.php：

use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;  // 添加Passport特性
}

配置 config/auth.php：

'guards' => [
    'api' => [
        'driver' => 'passport',  // 使用Passport驱动
        'provider' => 'users',
    ],
],

---

3. 注册路由

在 routes/api.php 添加：

use Laravel\Passport\Http\Controllers as PassportControllers;

// OAuth2 授权端点
Route::post('/oauth/token', [PassportControllers\AccessTokenController::class, 'issueToken']);

// 第三方登录回调
Route::get('/oauth/callback', [OAuthController::class, 'handleCallback']);

---

4. 创建客户端凭证

php artisan passport:client --password  # 创建密码授权客户端

输出示例：

Client ID: 3
Client secret: abcdefghijklmnopqrstuvwxyz

---

5. 实现控制器逻辑

App\Http\Controllers\OAuthController.php：

public function redirectToProvider()
{
    $query = http_build_query([
        'client_id' => env('OAUTH_CLIENT_ID'),
        'redirect_uri' => env('OAUTH_REDIRECT_URI'),
        'response_type' => 'code',
        'scope' => '',
    ]);

    return redirect('https://third-party.com/oauth/authorize?'.$query);
}

public function handleCallback(Request $request)
{
    $response = Http::post(env('OAUTH_TOKEN_URL'), [
        'grant_type' => 'authorization_code',
        'client_id' => env('OAUTH_CLIENT_ID'),
        'client_secret' => env('OAUTH_CLIENT_SECRET'),
        'redirect_uri' => env('OAUTH_REDIRECT_URI'),
        'code' => $request->code,
    ]);

    $accessToken = $response->json()['access_token'];
    // 使用$accessToken获取用户数据
}

---

6. 环境配置 (.env)

OAUTH_CLIENT_ID=3
OAUTH_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz
OAUTH_REDIRECT_URI=https://yourdomain.com/oauth/callback
OAUTH_TOKEN_URL=https://third-party.com/oauth/token

---

关键安全措施

1. CSRF 保护：所有回调路由使用 VerifyCsrfToken 中间件
2. 令牌有效期：在 App\Providers\AuthServiceProvider 配置令牌生命周期

   Passport::tokensExpireIn(now()->addDays(15));
   

3. 范围验证：使用 scope 参数限制权限

   Passport::setDefaultScope([
       'user:profile'
   ]);
   

测试流程

1. 访问 /oauth/redirect 触发第三方登录
2. 在第三方平台完成授权
3. 回调到 /oauth/callback 获取令牌
4. 使用令牌访问受保护 API 端点

提示：使用 Postman 测试 OAuth2 流程时，选择 Authorization Code 模式并填入客户端凭证

常见问题解决

• 令牌无效：检查客户端密钥和回调 URL 是否匹配
• 跨域问题：配置 config/cors.php 允许第三方域名
• 密钥轮换：定期执行 php artisan passport:keys 更新加密密钥

此方案符合 OAuth2.0 规范，支持 GitHub/Google/Facebook 等主流平台登录集成，完整文档参考 Laravel Passport 官方文档。