Laravel Socialite

• 介绍
• 安装
• 升级 Socialite
• 配置
• 认证
  • 路由
  • 认证与存储
  • 访问范围
  • 可选参数
• 检索用户详情

介绍

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

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

安装

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

composer require laravel/socialite

升级 Socialite

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

配置

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

这些凭据应放置在应用程序的 config/services.php 配置文件中，并应使用 facebook、twitter（OAuth 1.0）、twitter-oauth-2（OAuth 2.0）、linkedin、google、github、gitlab 或 bitbucket 作为键，具体取决于应用程序所需的提供商：

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

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

访问范围

在将用户重定向之前，您可以使用 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();

可选参数

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

use Laravel\Socialite\Facades\Socialite;

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

使用 with 方法时，请Note不要传递任何保留关键字，如 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 提供商...
    $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();
});

从令牌检索用户详情（OAuth2）

如果您已经拥有用户的有效访问令牌，可以使用 Socialite 的 userFromToken 方法检索其用户详情：

use Laravel\Socialite\Facades\Socialite;

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

从令牌和密钥检索用户详情（OAuth1）

如果您已经拥有用户的有效令牌和密钥，可以使用 Socialite 的 userFromTokenAndSecret 方法检索其用户详情：

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

无状态认证

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

use Laravel\Socialite\Facades\Socialite;

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

无状态认证不适用于 Twitter OAuth 1.0 驱动程序。