Laravel Socialite
简介
除了传统的基于表单的身份验证外，Laravel 还提供了一种简单、便捷的方法，通过 Laravel Socialite 使用 OAuth 提供商进行身份验证。Socialite 目前支持通过 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 进行身份验证。
其他平台的适配器可通过社区驱动的 Socialite Providers 网站获取。
安装
要开始使用 Socialite，请使用 Composer 包管理器将该包添加到项目的依赖项中
1composer require laravel/socialite升级 Socialite
升级到 Socialite 的新主版本时，请务必仔细阅读 升级指南。
配置
在使用 Socialite 之前，您需要为您应用所使用的 OAuth 提供商添加凭据。通常，这些凭据可以通过在您要进行身份验证的服务仪表板中创建“开发者应用”来获取。
这些凭据应放置在您应用的 config/services.php 配置文件中，并根据您的应用所需的提供商，使用 facebook、x、linkedin-openid、google、github、gitlab、bitbucket、slack 或 slack-openid 作为键。
1'github' => [2 'client_id' => env('GITHUB_CLIENT_ID'),3 'client_secret' => env('GITHUB_CLIENT_SECRET'),4 'redirect' => 'http://example.com/callback-url',5],如果 redirect 选项包含相对路径，它将自动解析为完全限定的 URL。
认证
路由
要使用 OAuth 提供商验证用户身份，您需要两条路由：一条用于将用户重定向到 OAuth 提供商，另一条用于在身份验证后接收来自提供商的回调。下面的示例路由演示了这两条路由的实现
1use Laravel\Socialite\Socialite; 2 3Route::get('/auth/redirect', function () { 4 return Socialite::driver('github')->redirect(); 5}); 6 7Route::get('/auth/callback', function () { 8 $user = Socialite::driver('github')->user(); 9 10 // $user->token11});Socialite 门面提供的 redirect 方法负责将用户重定向到 OAuth 提供商，而 user 方法则会检查传入的请求，并在用户批准身份验证请求后从提供商处检索用户信息。
身份验证与存储
从 OAuth 提供商获取用户信息后，您可以确定该用户是否存在于您的应用数据库中并 对用户进行身份验证。如果该用户不存在于您的数据库中，您通常会在数据库中创建一个新记录来代表该用户。
1use App\Models\User; 2use Illuminate\Support\Facades\Auth; 3use Laravel\Socialite\Socialite; 4 5Route::get('/auth/callback', function () { 6 $githubUser = Socialite::driver('github')->user(); 7 8 $user = User::updateOrCreate([ 9 'github_id' => $githubUser->id,10 ], [11 'name' => $githubUser->name,12 'email' => $githubUser->email,13 'github_token' => $githubUser->token,14 'github_refresh_token' => $githubUser->refreshToken,15 ]);16 17 Auth::login($user);18 19 return redirect('/dashboard');20});有关特定 OAuth 提供商可提供哪些用户信息的更多信息，请参阅 获取用户详细信息 的文档。
访问范围 (Access Scopes)
在重定向用户之前，您可以使用 scopes 方法来指定身份验证请求中应包含的“作用域 (scopes)”。此方法会将之前指定的所有作用域与您当前指定的作用域合并。
1use Laravel\Socialite\Socialite;2 3return Socialite::driver('github')4 ->scopes(['read:user', 'public_repo'])5 ->redirect();您可以使用 setScopes 方法覆盖身份验证请求上所有现有的作用域。
1return Socialite::driver('github')2 ->setScopes(['read:user', 'public_repo'])3 ->redirect();Slack 机器人作用域
Slack 的 API 提供了 不同类型的访问令牌，每种都有其对应的 权限作用域。Socialite 兼容以下两种 Slack 访问令牌类型：
- Bot（前缀为
xoxb-） - User（前缀为
xoxp-）
默认情况下，slack 驱动程序将生成一个 user 令牌，调用驱动程序的 user 方法将返回用户的详细信息。
如果您希望应用向由应用用户拥有的外部 Slack 工作区发送通知，Bot 令牌非常有用。要生成 Bot 令牌，请在将用户重定向到 Slack 进行身份验证之前调用 asBotUser 方法。
1return Socialite::driver('slack')2 ->asBotUser()3 ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])4 ->redirect();此外，在 Slack 将用户重定向回您的应用进行身份验证后，您必须在调用 user 方法之前调用 asBotUser 方法。
1$user = Socialite::driver('slack')->asBotUser()->user();生成 Bot 令牌时，user 方法仍会返回 Laravel\Socialite\Two\User 实例；但是，只有 token 属性会被填充。此令牌可以存储起来，以便 向已验证用户的 Slack 工作区发送通知。
可选参数
许多 OAuth 提供商支持重定向请求中的其他可选参数。要在请求中包含任何可选参数，请使用关联数组调用 with 方法。
1use Laravel\Socialite\Socialite;2 3return Socialite::driver('google')4 ->with(['hd' => 'example.com'])5 ->redirect();使用 with 方法时，请注意不要传递任何保留关键字，例如 state 或 response_type。
获取用户详细信息
在用户被重定向回您的应用身份验证回调路由后，您可以使用 Socialite 的 user 方法检索用户的详细信息。user 方法返回的用户对象提供了多种属性和方法，您可以使用它们将用户信息存储在自己的数据库中。
根据您进行身份验证的 OAuth 提供商是否支持 OAuth 1.0 或 OAuth 2.0，此对象上可能提供不同的属性和方法。
1use Laravel\Socialite\Socialite; 2 3Route::get('/auth/callback', function () { 4 $user = Socialite::driver('github')->user(); 5 6 // OAuth 2.0 providers... 7 $token = $user->token; 8 $refreshToken = $user->refreshToken; 9 $expiresIn = $user->expiresIn;10 11 // OAuth 1.0 providers...12 $token = $user->token;13 $tokenSecret = $user->tokenSecret;14 15 // All providers...16 $user->getId();17 $user->getNickname();18 $user->getName();19 $user->getEmail();20 $user->getAvatar();21});从令牌获取用户详细信息
如果您已经拥有用户的有效访问令牌，则可以使用 Socialite 的 userFromToken 方法获取他们的用户详细信息。
1use Laravel\Socialite\Socialite;2 3$user = Socialite::driver('github')->userFromToken($token);如果您通过 iOS 应用使用 Facebook Limited Login，Facebook 将返回 OIDC 令牌而不是访问令牌。与访问令牌一样，OIDC 令牌可以提供给 userFromToken 方法以获取用户详细信息。
无状态身份验证 (Stateless Authentication)
stateless 方法可用于禁用会话状态验证。这在将社交登录功能添加到不使用基于 Cookie 会话的无状态 API 时非常有用。
1use Laravel\Socialite\Socialite;2 3return Socialite::driver('google')->stateless()->user();测试
Laravel Socialite 提供了一种便捷的方法来测试 OAuth 身份验证流程，而无需向 OAuth 提供商发出实际请求。fake 方法允许您模拟 OAuth 提供商的行为并定义应返回的用户数据。
模拟重定向
要测试您的应用是否正确地将用户重定向到 OAuth 提供商，您可以在请求重定向路由之前调用 fake 方法。这将导致 Socialite 返回一个指向模拟授权 URL 的重定向，而不是重定向到实际的 OAuth 提供商。
1use Laravel\Socialite\Socialite;2 3test('user is redirected to github', function () {4 Socialite::fake('github');5 6 $response = $this->get('/auth/github/redirect');7 8 $response->assertRedirect();9});模拟回调
要测试应用的重定向回调路由，您可以调用 fake 方法并提供一个 User 实例，该实例将在应用请求从提供商处获取用户详细信息时返回。User 实例可以使用 map 方法创建。
1use Laravel\Socialite\Socialite; 2use Laravel\Socialite\Two\User; 3 4test('user can login with github', function () { 5 Socialite::fake('github', (new User)->map([ 6 'id' => 'github-123', 7 'name' => 'Jason Beggs', 9 ]));10 11 $response = $this->get('/auth/github/callback');12 13 $response->assertRedirect('/dashboard');14 15 $this->assertDatabaseHas('users', [16 'name' => 'Jason Beggs',18 'github_id' => 'github-123',19 ]);20});默认情况下，User 实例还将包含一个 token 属性。如果需要，您可以手动在 User 实例上指定其他属性。
1$fakeUser = (new User)->map([2 'id' => 'github-123',3 'name' => 'Jason Beggs',5])->setToken('fake-token')6 ->setRefreshToken('fake-refresh-token')7 ->setExpiresIn(3600)8 ->setApprovedScopes(['read', 'write'])