Laravel Socialite

• 简介
• 安装
• 升级 Socialite
• 配置
• 身份验证
  • 路由
  • 身份验证和存储
  • 访问范围
  • Slack Bot 范围
  • 可选参数
• 检索用户详细信息

简介

除了典型的基于表单的身份验证之外，Laravel 还提供了一种简单方便的方式，可以使用 Laravel Socialite 通过 OAuth 提供程序进行身份验证。Socialite 目前支持通过 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 进行身份验证。

安装

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

composer require laravel/socialite

升级 Socialite

升级到 Socialite 的新主要版本时，请务必仔细查看 升级指南。

配置

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

这些凭据应放置在应用程序的 config/services.php 配置文件中，并且应使用键 facebook、x、linkedin-openid、google、github、gitlab、bitbucket、slack 或 slack-openid，具体取决于你的应用程序所需的提供程序

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => 'http://example.com/callback-url',
],

身份验证

路由

要使用 OAuth 提供程序对用户进行身份验证，你需要两条路由：一条用于将用户重定向到 OAuth 提供程序，另一条用于在身份验证后接收来自提供程序的回调。下面的示例路由演示了这两条路由的实现

use Laravel\Socialite\Facades\Socialite;
 
Route::get('/auth/redirect', function () {
    return Socialite::driver('github')->redirect();
});
 
Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();
 
    // $user->token
});

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

身份验证和存储

从 OAuth 提供程序检索到用户后，你可以确定该用户是否存在于应用程序的数据库中，并对用户进行身份验证。如果用户的数据库中不存在该用户，你通常会在数据库中创建一个新记录来表示该用户

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;
 
Route::get('/auth/callback', function () {
    $githubUser = Socialite::driver('github')->user();
 
    $user = User::updateOrCreate([
        'github_id' => $githubUser->id,
    ], [
        'name' => $githubUser->name,
        'email' => $githubUser->email,
        'github_token' => $githubUser->token,
        'github_refresh_token' => $githubUser->refreshToken,
    ]);
 
    Auth::login($user);
 
    return redirect('/dashboard');
});

访问范围

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

use Laravel\Socialite\Facades\Socialite;
 
return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

你可以使用 setScopes 方法覆盖身份验证请求中的所有现有范围

return Socialite::driver('github')
    ->setScopes(['read:user', 'public_repo'])
    ->redirect();

Slack Bot 范围

Slack 的 API 提供不同类型的访问令牌，每种令牌都有自己的权限范围。Socialite 与以下两种 Slack 访问令牌类型兼容

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

如果你的应用程序将向应用程序用户的外部 Slack 工作区发送通知，则 Bot 令牌主要有用。要生成 Bot 令牌，请在将用户重定向到 Slack 进行身份验证之前调用 asBotUser 方法

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

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

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

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

可选参数

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

use Laravel\Socialite\Facades\Socialite;
 
return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

检索用户详细信息

在用户重定向回应用程序的身份验证回调路由后，你可以使用 Socialite 的 user 方法检索用户的详细信息。user 方法返回的用户对象提供了多种属性和方法，你可以使用这些属性和方法将有关用户的信息存储在你自己的数据库中。

此对象上可能会提供不同的属性和方法，具体取决于你进行身份验证的 OAuth 提供程序是否支持 OAuth 1.0 或 OAuth 2.0

use Laravel\Socialite\Facades\Socialite;
 
Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();
 
    // OAuth 2.0 providers...
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;
 
    // OAuth 1.0 providers...
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;
 
    // All providers...
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

从令牌检索用户详细信息

如果你已经拥有用户的有效访问令牌，则可以使用 Socialite 的 userFromToken 方法检索其用户详细信息

use Laravel\Socialite\Facades\Socialite;
 
$user = Socialite::driver('github')->userFromToken($token);

如果你正在通过 iOS 应用程序使用 Facebook Limited Login，Facebook 将返回 OIDC 令牌而不是访问令牌。与访问令牌一样，可以将 OIDC 令牌提供给 userFromToken 方法，以便检索用户详细信息。

无状态身份验证

stateless 方法可用于禁用会话状态验证。当将社交身份验证添加到不使用基于 Cookie 的会话的无状态 API 时，这非常有用

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