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 提供者，另一個用於接收來自提供者在身份驗證後的 callback。以下範例路由示範了這兩個路由的實作

 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 facade 提供的 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。

檢索使用者詳細資訊

在使用者重新導向回應用程式的身份驗證 callback 路由後，您可以使用 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 方法可用於停用 session 狀態驗證。當將社交身份驗證新增至不使用基於 Cookie 的 session 的無狀態 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 範圍

選用參數

檢索使用者詳細資訊

從權杖檢索使用者詳細資訊

無狀態身份驗證

產品

套件

資源