Laravel Socialite

• 簡介
• 安裝
• 升級 Socialite
• 設定
• 身份驗證
  • 路由
  • 身份驗證和儲存
  • 存取範圍
  • Slack Bot 範圍
  • 可選參數
• 擷取使用者詳細資訊

簡介

除了典型的表單身份驗證之外，Laravel 還提供了一種簡單方便的方法，使用 Laravel Socialite 透過 OAuth 提供者進行身份驗證。Socialite 目前支援透過 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 進行身份驗證。

安裝

若要開始使用 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',
],

身份驗證

路由

若要使用 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');
});

存取範圍

在重新導向使用者之前，您可以使用 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();

Slack Bot 範圍

Slack 的 API 提供不同類型的存取權杖，每個權杖都有自己的一組權限範圍。Socialite 與以下兩種 Slack 存取權杖類型相容

預設情況下，slack 驅動程式會產生一個 user 權杖，而呼叫驅動程式的 user 方法會傳回使用者的詳細資訊。

如果您的應用程式會將通知傳送至您應用程式使用者擁有的外部 Slack 工作區，則 Bot 權杖主要有用。若要產生 Bot 權杖，請在將使用者重新導向至 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();

產生 Bot 權杖時，user 方法仍會傳回 Laravel\Socialite\Two\User 實例；但是，只會填入 token 屬性。可以儲存此權杖，以便將通知傳送至已驗證使用者的 Slack 工作區。

可選參數

許多 OAuth 提供者在重新導向請求上支援其他可選參數。若要在請求中包含任何可選參數，請使用關聯陣列呼叫 with 方法

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

擷取使用者詳細資訊

在使用者重新導向回您應用程式的身份驗證回調路由後，您可以使用 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 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\Facades\Socialite;
 
$user = Socialite::driver('github')->userFromToken($token);

如果您正在透過 iOS 應用程式使用 Facebook Limited Login，Facebook 將會傳回 OIDC 權杖，而不是存取權杖。與存取權杖一樣，OIDC 權杖可以提供給 userFromToken 方法，以便擷取使用者詳細資訊。

無狀態身份驗證

stateless 方法可用於停用會話狀態驗證。當將社群身份驗證新增至不使用基於 Cookie 的會話的無狀態 API 時，這很有用

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