Socialite-Laravel 文档-果果开发

简介

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

其他平台的适配器可通过社区驱动的 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',
],

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

认证

路由

要使用 OAuth 提供商进行用户认证，您需要两个路由：一个用于将用户重定向到 OAuth 提供商，另一个用于在认证后接收提供商的回调。下面的示例路由展示了这两个路由的实现方式：

use Laravel\Socialite\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\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');
});

如需了解特定 OAuth 提供商可提供的用户信息详情，请参阅获取用户详情的相关文档。

访问范围

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

use Laravel\Socialite\Socialite;

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

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

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

Slack 机器人范围

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

机器人（以 xoxb- 为前缀）
用户（以 xoxp- 为前缀）

默认情况下，slack 驱动会生成 user 令牌，调用该驱动的 user 方法会返回用户的详细信息。

机器人令牌主要适用于您的应用需要向应用用户所拥有的外部 Slack 工作区发送通知的场景。要生成机器人令牌，请在将用户重定向到 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();

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

可选参数

许多 OAuth 提供商在重定向请求中支持其他可选参数。要在请求中包含可选参数，可调用 with 方法并传入关联数组：

use Laravel\Socialite\Socialite;

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

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

获取用户详情

当用户被重定向回应用的认证回调路由后，您可以使用 Socialite 的 user 方法获取用户详情。user 方法返回的用户对象提供了多种属性和方法，可用于将用户信息存储在您自己的数据库中。

根据您进行认证的 OAuth 提供商是否支持 OAuth 1.0 或 OAuth 2.0，该对象可能提供不同的属性和方法：

use Laravel\Socialite\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\Socialite;

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

如果您通过 iOS 应用使用 Facebook Limited Login，Facebook 会返回 OIDC 令牌而非访问令牌。要从 OIDC 令牌获取用户详情，请将启动登录时使用的 nonce 提供给 userFromToken 方法：

$user = Socialite::driver('facebook')->userFromToken($token, $nonce);

无状态认证

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

use Laravel\Socialite\Socialite;

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

测试

Laravel Socialite 提供了一种便捷的方式来测试 OAuth 认证流程，无需实际向 OAuth 提供商发送请求。fake 方法允许您模拟 OAuth 提供商的行为，并定义应返回的用户数据。

伪造重定向

若要测试你的应用能否正确地将用户重定向到 OAuth 提供商，可以在向重定向路由发起请求之前调用 fake 方法。这会让 Socialite 返回重定向到模拟授权 URL 的结果，而不会重定向到真实的 OAuth 提供商：

use Laravel\Socialite\Socialite;

test('user is redirected to github', function () {
    Socialite::fake('github');

    $response = $this->get('/auth/github/redirect');

    $response->assertRedirect();
});

模拟回调

若要测试应用的回调路由，你可以调用 fake 方法，并提供一个 User 实例，当应用从提供商处请求用户详细信息时应返回该实例。可以使用 fake 方法创建 User 实例：

use Laravel\Socialite\Socialite;
use Laravel\Socialite\Two\User;

test('user can login with github', function () {
    Socialite::fake('github', User::fake([
        'id' => 'github-123',
        'name' => 'Jason Beggs',
        'email' => '[email protected]',
    ]));

    $response = $this->get('/auth/github/callback');

    $response->assertRedirect('/dashboard');

    $this->assertDatabaseHas('users', [
        'name' => 'Jason Beggs',
        'email' => '[email protected]',
        'github_id' => 'github-123',
    ]);
});

默认情况下，User 实例会包含模拟的 OAuth 令牌值。如有必要，你可以通过向 fake 方法传递额外的属性来覆盖这些值：

$fakeUser = User::fake([
    'id' => 'github-123',
    'name' => 'Jason Beggs',
    'email' => '[email protected]',
    'token' => 'fake-token',
    'refreshToken' => 'fake-refresh-token',
    'expiresIn' => 3600,
    'approvedScopes' => ['read', 'write'],
]);

OAuth 1 用户可以使用 Laravel\Socialite\One\User 类进行模拟。