Laravel Socialite

简介

除了常见的基于表单的认证外，Laravel 还通过 Laravel Socialite 提供了一种简单、便捷的方式，通过 OAuth 提供商进行认证。Socialite 目前支持通过 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 进行认证。

INFO

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

安装

要开始使用 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',
],

INFO

如果 redirect 选项包含相对路径，它会自动解析为完整的绝对 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 facade 提供的 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');
});

INFO

关于各 OAuth 提供商可提供哪些用户信息，请参阅获取用户详情文档。

访问范围（Scopes）

在重定向用户之前，你可以使用 scopes 方法指定应包含在认证请求中的「scopes」。该方法会将之前已指定的所有 scopes 与你指定的 scopes 合并：

use Laravel\Socialite\Facades\Socialite;

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

你可以使用 setScopes 方法覆盖认证请求上已有的全部 scopes：

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

Slack Bot Scopes

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

• Bot（前缀为 `xoxb-`）
• User（前缀为 `xoxp-`）

默认情况下，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();

WARNING

使用 with 方法时，请注意不要传入 state 或 response_type 等保留关键字。

获取用户详情

用户被重定向回应用的认证回调路由后，你可以使用 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 token 而非 access token。与 access token 一样，可将 OIDC token 传给 userFromToken 方法以获取用户详情。

无状态认证

stateless 方法可用于禁用 session 状态校验。在向不使用基于 Cookie 的 session 的无状态 API 添加社交认证时，这一点很有用：

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')->stateless()->user();