Laravel Socialite

简介
安装
升级 Socialite
配置
身份验证
检索用户详细信息

简介

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

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

安装

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

1composer require laravel/socialite

composer require laravel/socialite

升级 Socialite

当升级到新版本的 Socialite 时，请务必仔细阅读升级指南。

配置

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

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

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

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

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

身份验证

路由

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

 1use Laravel\Socialite\Facades\Socialite;
 2 
 3Route::get('/auth/redirect', function () {
 4    return Socialite::driver('github')->redirect();
 5});
 6 
 7Route::get('/auth/callback', function () {
 8    $user = Socialite::driver('github')->user();
 9 
10    // $user->token
11});

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 提供程序检索用户后，您可以确定用户的数据库中是否存在该用户，并验证用户身份。如果用户的数据库中不存在该用户，您通常会在数据库中创建一个新记录来表示该用户

 1use App\Models\User;
 2use Illuminate\Support\Facades\Auth;
 3use Laravel\Socialite\Facades\Socialite;
 4 
 5Route::get('/auth/callback', function () {
 6    $githubUser = Socialite::driver('github')->user();
 7 
 8    $user = User::updateOrCreate([
 9        'github_id' => $githubUser->id,
10    ], [
11        'name' => $githubUser->name,
12        'email' => $githubUser->email,
13        'github_token' => $githubUser->token,
14        'github_refresh_token' => $githubUser->refreshToken,
15    ]);
16 
17    Auth::login($user);
18 
19    return redirect('/dashboard');
20});

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 方法指定应包含在身份验证请求中的“范围”。此方法会将所有先前指定的范围与您指定的范围合并

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

use Laravel\Socialite\Facades\Socialite;

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

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

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

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

Slack Bot 范围

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

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

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

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

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

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

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

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

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

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

可选参数

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

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

use Laravel\Socialite\Facades\Socialite;

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

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

检索用户详细信息

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

此对象上可用的不同属性和方法可能取决于您正在进行身份验证的 OAuth 提供程序是否支持 OAuth 1.0 或 OAuth 2.0

 1use Laravel\Socialite\Facades\Socialite;
 2 
 3Route::get('/auth/callback', function () {
 4    $user = Socialite::driver('github')->user();
 5 
 6    // OAuth 2.0 providers...
 7    $token = $user->token;
 8    $refreshToken = $user->refreshToken;
 9    $expiresIn = $user->expiresIn;
10 
11    // OAuth 1.0 providers...
12    $token = $user->token;
13    $tokenSecret = $user->tokenSecret;
14 
15    // All providers...
16    $user->getId();
17    $user->getNickname();
18    $user->getName();
19    $user->getEmail();
20    $user->getAvatar();
21});

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 方法检索其用户详细信息

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

use Laravel\Socialite\Facades\Socialite;

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

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

无状态身份验证

stateless 方法可用于禁用会话状态验证。当向不使用基于 Cookie 的会话的无状态 API 添加社交身份验证时，此方法很有用

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

use Laravel\Socialite\Facades\Socialite;

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

序言

入门指南

架构概念

基础知识

深入探讨

安全

数据库

Eloquent ORM

测试

软件包

Laravel Socialite

简介

安装

升级 Socialite

配置

身份验证

路由

身份验证和存储

访问范围

Slack Bot 范围

可选参数

检索用户详细信息

从令牌检索用户详细信息

无状态身份验证

产品

软件包

资源