后盾人

Appearance

Laravel Socialite ​

简介 ​

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

[!注意]
其他平台的适配器可以通过社区驱动的 Socialite Providers 网站获得。

安装 ​

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

shell
composer require laravel/socialite

升级 Socialite ​

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

配置 ​

在使用 Socialite 之前，您需要为 OAuth 提供商添加凭证。通常，这些凭证可以通过在服务的控制台中创建一个“开发者应用”来获取。

这些凭证应该放在应用程序的 config/services.php 配置文件中，并使用 facebook、twitter (OAuth 1.0)、twitter-oauth-2 (OAuth 2.0)、linkedin-openid、google、github、gitlab、bitbucket、slack 或 slack-openid 作为关键字，具体取决于您的应用程序所需的提供商:

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

[!注意]
如果 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
    });

redirect 方法由 Socialite facade 提供，负责将用户重定向到 OAuth 提供商，而 user 方法将检查 incoming 请求并从提供商中检索用户信息。

认证和存储 ​

在用户从 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');
    });

[!注意]
有关从特定 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 访问令牌类型:

  • Bot (前缀为 xoxb-)
  • User (前缀为 xoxp-)

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

Bot 令牌主要有用，如果您的应用程序将向外部 Slack 工作空间（由您的应用程序的用户拥有）发送通知。要生成 Bot 令牌，请在重定向用户到 Slack 进行认证之前调用 asBotUser 方法:

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

此外，您必须在 Slack 重定向用户回应用程序后认证时调用 asBotUser 方法:

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

当生成 Bot 令牌时，user 方法仍然会返回一个 Laravel\Socialite\Two\User 实例；然而，只有 token 属性会被填充。您可以将此令牌存储以 向认证用户的 Slack 工作空间发送通知。

可选参数 ​

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

php
    use Laravel\Socialite\Facades\Socialite;

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

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

获取用户详细信息 ​

在用户被重定向回应用程序的认证回调路由后，您可以使用 Socialite 的 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();
    });

从令牌中获取用户详细信息 (OAuth2) ​

如果您已经有一个有效的访问令牌，则可以使用 Socialite 的 userFromToken 方法获取用户详细信息:

php
    use Laravel\Socialite\Facades\Socialite;

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

如果您使用 Facebook Limited Login 进行 iOS 应用程序认证，则 Facebook 将返回一个 OIDC 令牌，而不是访问令牌。与访问令牌一样，您可以将 OIDC 令牌提供给 userFromToken 方法以获取用户详细信息。

从令牌和密钥中获取用户详细信息 (OAuth1) ​

如果您已经有一个有效的令牌和密钥，则可以使用 Socialite 的 userFromTokenAndSecret 方法获取用户详细信息:

php
    use Laravel\Socialite\Facades\Socialite;

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

无状态认证 ​

您可以使用 stateless 方法来禁用会话状态验证。这对于添加社交认证到不使用基于 cookie 的会话的无状态 API 有用:

php
    use Laravel\Socialite\Facades\Socialite;

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

[!注意]
无状态认证对于 Twitter OAuth 1.0 驱动程序不可用。

后盾人版权所有 © 2018-2025 创作不易请尊重他人劳动成果，未经授权禁止转载！