Laravel Socialite

簡介
安裝
升級 Socialite
配置
認證
檢索使用者詳細資訊
測試

簡介

除了典型的基於表單的認證之外，Laravel 還提供了一種簡單且便利的方式，可以使用 Laravel Socialite 與 OAuth 提供者進行認證。Socialite 目前支援透過 Facebook、X、LinkedIn、Google、GitHub、GitLab、Bitbucket 和 Slack 進行認證。

[!NOTE] 其他平台的適配器可透過社群驅動的 Socialite Providers 網站獲取。

安裝

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

[!NOTE] 如果 redirect 選項包含相對路徑，它將自動解析為完全限定的 URL。

認證

路由

要使用 OAuth 提供者認證使用者，您需要兩個路由：一個用於將使用者重定向到 OAuth 提供者，另一個用於在認證後接收來自提供者的回呼。以下範例路由演示了這兩個路由的實現：

use Laravel\Socialite\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 提供者檢索到使用者，您就可以判斷該使用者是否存在於應用程式的資料庫中，並認證該使用者。如果使用者不存在於應用程式的資料庫中，您通常會在資料庫中建立一個新記錄來代表該使用者：

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\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');
});

[!NOTE] 有關特定 OAuth 提供者可用的使用者資訊，請查閱檢索使用者詳細資訊的文件。

存取範圍

在重定向使用者之前，您可以使用 scopes 方法指定應包含在認證請求中的「範圍」。此方法將合併所有先前指定的範圍與您指定的範圍：

use Laravel\Socialite\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 存取令牌類型相容：

Bot（以 xoxb- 為前綴）
User（以 xoxp- 為前綴）

預設情況下，slack 驅動程式將生成一個 user 令牌，呼叫驅動程式的 user 方法將返回使用者的詳細資訊。

Bot 令牌主要在您的應用程式將向使用者擁有的外部 Slack 工作區發送通知時很有用。要生成 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\Socialite;

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

[!WARNING] 使用 with 方法時，請小心不要傳遞任何保留字，例如 state 或 response_type。

檢索使用者詳細資訊

使用者被重定向回應用程式的認證回呼路由後，您可以使用 Socialite 的 user 方法檢索使用者的詳細資訊。user 方法返回的使用者物件提供了各種屬性和方法，您可以用它們來在自己的資料庫中儲存使用者的資訊。

根據您進行認證的 OAuth 提供者支援 OAuth 1.0 還是 OAuth 2.0，此物件上可能有不同的屬性和方法：

use Laravel\Socialite\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();
});

從令牌檢索使用者詳細資訊

如果您已經擁有使用者的有效存取令牌，您可以使用 Socialite 的 userFromToken 方法檢索其使用者詳細資訊：

use Laravel\Socialite\Socialite;

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

如果您正在透過 iOS 應用程式使用 Facebook Limited Login，Facebook 將返回一個 OIDC 令牌而不是存取令牌。像存取令牌一樣，OIDC 令牌可以提供給 userFromToken 方法以檢索使用者詳細資訊。

無狀態認證

stateless 方法可用於禁用 session 狀態驗證。這在向不使用基於 cookie 的 session 的無狀態 API 添加社交認證時很有用：

use Laravel\Socialite\Socialite;

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

測試

Laravel Socialite 提供了一種便利的方式來測試 OAuth 認證流程，而無需向 OAuth 提供者發送實際請求。fake 方法允許您模擬 OAuth 提供者的行為並定義應返回的使用者資料。

模擬重定向

要測試應用程式是否正確地將使用者重定向到 OAuth 提供者，您可以在向重定向路由發送請求之前呼叫 fake 方法。這將導致 Socialite 返回一個指向假授權 URL 的重定向，而不是重定向到實際的 OAuth 提供者：

use Laravel\Socialite\Socialite;

test('user is redirected to github', function () {
    Socialite::fake('github');

    $response = $this->get('/auth/github/redirect');

    $response->assertRedirect();
});

模擬回呼

要測試應用程式的回呼路由，您可以呼叫 fake 方法並提供一個 User 實例，該實例應在您的應用程式向提供者請求使用者詳細資訊時返回。User 實例可以使用 fake 方法建立：

use Laravel\Socialite\Socialite;
use Laravel\Socialite\Two\User;

test('user can login with github', function () {
    Socialite::fake('github', User::fake([
        'id' => 'github-123',
        'name' => 'Jason Beggs',
        'email' => '[email protected]',
    ]));

    $response = $this->get('/auth/github/callback');

    $response->assertRedirect('/dashboard');

    $this->assertDatabaseHas('users', [
        'name' => 'Jason Beggs',
        'email' => '[email protected]',
        'github_id' => 'github-123',
    ]);
});

預設情況下，User 實例將包含假的 OAuth 令牌值。如果需要，您可以透過向 fake 方法傳遞額外的屬性來覆蓋這些值：

$fakeUser = User::fake([
    'id' => 'github-123',
    'name' => 'Jason Beggs',
    'email' => '[email protected]',
    'token' => 'fake-token',
    'refreshToken' => 'fake-refresh-token',
    'expiresIn' => 3600,
    'approvedScopes' => ['read', 'write'],
]);

OAuth 1 使用者可以使用 Laravel\Socialite\One\User 類別來模擬。