跳至内容

Laravel 社交名流

介绍

除了典型的基于表单的身份验证之外，Laravel 还提供了一种简单便捷的方法，即通过Laravel Socialite与 OAuth 提供商进行身份验证。Socialite 目前支持通过 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 进行身份验证。

可通过社区驱动的Socialite Providers网站获取其他平台的适配器。

安装

要开始使用 Socialite，请使用 Composer 包管理器将包添加到项目的依赖项中：

1composer require laravel/socialite

升级社交名流

当升级到 Socialite 的新主要版本时，仔细阅读升级指南非常重要。

配置

在使用 Socialite 之前，您需要为应用程序所使用的 OAuth 提供商添加凭据。通常，您可以在要进行身份验证的服务的仪表板中创建“开发者应用程序”来获取这些凭据。

这些凭证应放在应用程序的config/services.php配置文件中，并且应使用密钥facebook、x、linkedin-openid、google、github、gitlab、或，bitbucket具体取决于应用程序所需的提供程序：slackslack-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\Facades\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->token
11});

redirect外观提供的方法负责Socialite将用户重定向到 OAuth 提供程序，同时该user方法将检查传入的请求并在提供程序批准身份验证请求后从提供程序检索用户的信息。

身份验证和存储

从 OAuth 提供程序获取到用户后，您可以判断该用户是否存在于应用程序数据库中，并对其进行身份验证。如果该用户不存在于应用程序数据库中，通常会在数据库中创建一条新记录来表示该用户：

 1use App\Models\User;
 2use Illuminate\Support\Facades\Auth;
 3use Laravel\Socialite\Facades\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 提供商提供哪些用户信息的更多信息，请参阅有关检索用户详细信息的文档。

访问范围

在重定向用户之前，您可以使用该scopes方法指定应包含在身份验证请求中的“作用域”。此方法会将所有先前指定的作用域与您指定的作用域合并：

1use Laravel\Socialite\Facades\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-）
  • 用户（以 为前缀xoxp-）

默认情况下，slack驱动程序将生成一个user令牌，调用驱动程序的user方法将返回用户的详细信息。

如果您的应用程序要向应用程序用户拥有的外部 Slack 工作区发送通知，则机器人令牌将非常有用。要生成机器人令牌，请asBotUser在将用户重定向到 Slack 进行身份验证之前调用该方法：

1return Socialite::driver('slack')
2    ->asBotUser()
3    ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
4    ->redirect();

此外，在 Slack 进行身份验证后将用户重定向回您的应用程序后，您必须asBotUser在调用该方法之前调用该方法：user

1$user = Socialite::driver('slack')->asBotUser()->user();

生成机器人令牌时，该user方法仍将返回一个Laravel\Socialite\Two\User实例；但是，只有token属性会被“hydrated”。此令牌可能会被存储，以便向已验证用户的 Slack 工作区发送通知。

可选参数

许多 OAuth 提供商支持在重定向请求中添加其他可选参数。要在请求中包含任何可选参数，请with使用关联数组调用该方法：

1use Laravel\Socialite\Facades\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\Facades\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\Facades\Socialite;
2 
3$user = Socialite::driver('github')->userFromToken($token);

如果您通过 iOS 应用程序使用 Facebook Limited Login，Facebook 将返回 OIDC 令牌而非访问令牌。与访问令牌类似，OIDC 令牌也可以提供给该userFromToken方法，以便检索用户详细信息。

无状态身份验证

该stateless方法可用于禁用会话状态验证。当向不使用基于 Cookie 的会话的无状态 API 添加社交身份验证时，此功能非常有用：

1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('google')->stateless()->user();