Laravel Socialite

• 簡介
• 安裝
• 更新 Socialite
• 設定
• 身份認證
  • Routing
  • 身份認證與檔案儲存
  • 存取範圍 (Scope)
  • 可選參數
• 取得使用者的詳細資訊

簡介

除了一般基於表單的登入方式之外，在 Laravel 中，還可以通過 Laravel Socialite 來以簡單、方便的方式使用 OAuth Provider 登入。目前 Socialite 支援使用 Facebook、Twitter、LinkedIn、Google、GitHub、GitLab 和 Bitbucket 等服務來進行登入。

安裝

若要開始使用 Socialite，請使用 Composer 套件管理器將 Socialite 套件新增至專案的相依性套件中：

1composer require laravel/socialite
1composer require laravel/socialite

更新 Socialite

將 Telescope 升級到新的主要 (Major) 版本時，請務必仔細閱讀升級指南。

設定

在使用 Socialite 之前，需要新增你的網站要使用的 OAuth Provider 憑證 (Credential)。一般來說，可以在要用來登入的服務的儀表板中建立「開發者應用程式」來取得這些憑證。

請將這些憑證放在專案的 config/services.php 設定檔中，並依照你的專案所要使用的 OAuth Provider，設定 facebook、twitter (OAuth 1.0)、twitter-oauth-2 (OAuth 2.0)、linkedin、google、github、gitlab 或 bitbucket 等相對應的 key：

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

登入

Routing

要使用 OAuth Provider 來登入使用者，需要兩個 Route：一個用來將使用者重新導向到 OAuth Provider，另一個用來接收登入後 Provider 傳回來的回呼。下面的範例說明如何實作這兩個 Route：

 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});
 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});

Socialite Facade 上的 redirect 方法負責將使用者重新導向到 OAuth Provider。當使用者同意登入要求後，user 方法會檢查傳入的 Request，並向 OAuth Provider 取得使用者的資訊。

登入與檔案儲存

從 OAuth Provider 取得使用者後，就可以判斷該使用者是否存在我們的網站中，並登入該使用者。如果使用者不存在網站資料庫中，可以在資料庫中建立：

 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});
 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});

Access Scope (存取範圍)

在為使用者重新導向前，我們可以使用 scopes 方法來指定這個登入驗證 Request 中要包含的「Scope (範圍)」。此方法會將所指定的 Scopes 與先前指定的所有 Scopes 合併起來：

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

可以使用 setScopes 方法來複寫登入驗證 Request 上的所有已存在的 Scopes：

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

可選的參數

有一些 OAuth Provider 還支援在重新導向 Request 上設定其他可選的參數。若要在 Request 中包含任何可選的參數，請呼叫 with 方法並提供一個關聯式陣列：

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

取得使用者詳細資料

使用者被重新導向到我們網站上的登入驗證 Callback(回呼) Route 後，就可以使用 Socialite 的 user 方法來取得使用者的詳細資料。user 方法回傳的使用者物件提供了多種屬性與方法，我們可以將與該使用者有關的資訊存在資料庫中。

根據所使用的 OAuth Provider 是支援 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 Provider...
 7    $token = $user->token;
 8    $refreshToken = $user->refreshToken;
 9    $expiresIn = $user->expiresIn;
10 
11    // OAuth 1.0 Provider...
12    $token = $user->token;
13    $tokenSecret = $user->tokenSecret;
14 
15    // 所有 Provider...
16    $user->getId();
17    $user->getNickname();
18    $user->getName();
19    $user->getEmail();
20    $user->getAvatar();
21});
 1use Laravel\Socialite\Facades\Socialite;
 2 
 3Route::get('/auth/callback', function () {
 4    $user = Socialite::driver('github')->user();
 5 
 6    // OAuth 2.0 Provider...
 7    $token = $user->token;
 8    $refreshToken = $user->refreshToken;
 9    $expiresIn = $user->expiresIn;
10 
11    // OAuth 1.0 Provider...
12    $token = $user->token;
13    $tokenSecret = $user->tokenSecret;
14 
15    // 所有 Provider...
16    $user->getId();
17    $user->getNickname();
18    $user->getName();
19    $user->getEmail();
20    $user->getAvatar();
21});

以 Token(權杖) 來取得使用者詳細資料 (OAuth2)

若你已經擁有使用者的有效 Access Token(存取權杖)，就可使用 Socialite 的 userFromToken 方法來取得該使用者的詳細資料：

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

以 Token(權杖) 與 Secret(密鑰) 來取得使用者詳細資料 (OAuth1)

若你已經擁有使用者的有效 Token(權杖) 與 Secret(密鑰)，就可使用 Socialite 的 userFromTokenAndSecret 方法來取得該使用者的詳細資料：

1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);
1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

Stateless(無周邊) 的登入驗證

使用 stateless 方法可關閉 Session 狀態驗證。此方法適合用於在不使用 Cookie 的 Stateless API 工作階段中加入社群網站登入。

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