Skip to content
赞助商赞助商赞助商
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待
虚位以待

Laravel Socialite

介绍

除了典型的基于表单的认证,Laravel 还提供了一种简单、方便的方法来使用 Laravel Socialite 进行 OAuth 提供者认证。Socialite 目前支持通过 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 进行认证。

NOTE

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

安装

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

shell
composer require laravel/socialite

升级 Socialite

在升级到 Socialite 的新主要版本时,务必仔细查看升级指南

配置

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

这些凭据应放置在应用程序的 config/services.php 配置文件中,并应使用 facebookxlinkedin-openidgooglegithubgitlabbitbucketslackslack-openid 作为键,具体取决于应用程序所需的提供者:

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

NOTE

如果 redirect 选项包含相对路径,它将自动解析为完全限定的 URL。

认证

路由

要使用 OAuth 提供者认证用户,您需要两个路由:一个用于将用户重定向到 OAuth 提供者,另一个用于在认证后从提供者接收回调。下面的示例路由演示了这两个路由的实现:

php
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 提供者检索到用户,您可以确定用户是否存在于应用程序的数据库中,并认证用户。如果用户不存在于应用程序的数据库中,通常会在数据库中创建一个新记录来表示用户:

php
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');
});

NOTE

有关从特定 OAuth 提供者可用的用户信息的更多信息,请查阅检索用户详情的文档。

访问范围

在将用户重定向之前,您可以使用 scopes 方法指定应包含在认证请求中的“范围”。此方法将合并所有先前指定的范围与您指定的范围:

php
use Laravel\Socialite\Facades\Socialite;

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

您可以使用 setScopes 方法覆盖认证请求上的所有现有范围:

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

Slack 机器人范围

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

  • 机器人(以 xoxb- 为前缀)
  • 用户(以 xoxp- 为前缀)

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

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

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

此外,您必须在 Slack 将用户重定向回应用程序进行认证后调用 user 方法之前调用 asBotUser 方法:

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

在生成机器人令牌时,user 方法仍将返回一个 Laravel\Socialite\Two\User 实例;然而,只有 token 属性将被填充。此令牌可以存储以便向认证用户的 Slack 工作区发送通知

可选参数

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

php
use Laravel\Socialite\Facades\Socialite;

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

WARNING

使用 with 方法时,请注意不要传递任何保留关键字,如 stateresponse_type

检索用户详情

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

根据您正在认证的 OAuth 提供者是否支持 OAuth 1.0 或 OAuth 2.0,此对象上可能会提供不同的属性和方法:

php
use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // OAuth 2.0 提供者...
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // OAuth 1.0 提供者...
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // 所有提供者...
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

从令牌检索用户详情

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

php
use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('github')->userFromToken($token);

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

无状态认证

stateless 方法可用于禁用会话状态验证。这在为不使用基于 cookie 的会话的无状态 API 添加社交认证时非常有用:

php
use Laravel\Socialite\Facades\Socialite;

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