Laravel Socialite

• 簡介

• 安裝

• 更新 Socialite

• 設定

• 身份認證

  • Routing
  • Authentication and Storage
  • 存取範圍 (Scope)
  • Slack Bot 的 Scope
  • 可選參數

• 取得使用者的詳細資訊

簡介

In addition to typical, form based authentication, Laravel also provides a simple, convenient way to authenticate with OAuth providers using Laravel Socialite. Socialite currently supports authentication via Facebook, X, LinkedIn, Google, GitHub, GitLab, Bitbucket, and Slack.

安裝

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

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

更新 Socialite

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

設定

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

These credentials should be placed in your application's config/services.php configuration file, and should use the key facebook, x, linkedin-openid, google, github, gitlab, bitbucket, slack, or slack-openid, depending on the providers your application requires:

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 取得使用者的資訊。

Authentication and Storage

從 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();

Slack Bot 的 Scope

Slack's API provides different types of access tokens, each with their own set of permission scopes. Socialite is compatible with both of the following Slack access tokens types:

By default, the slack driver will generate a user token and invoking the driver's user method will return the user's details.

Bot tokens are primarily useful if your application will be sending notifications to external Slack workspaces that are owned by your application's users. To generate a bot token, invoke the asBotUser method before redirecting the user to Slack for authentication:

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

In addition, you must invoke the asBotUser method before invoking the user method after Slack redirects the user back to your application after authentication:

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

When generating a bot token, the user method will still return a Laravel\Socialite\Two\User instance; however, only the token property will be hydrated. This token may be stored in order to send notifications to the authenticated user's Slack workspaces.

可選的參數

有一些 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 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});
 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});

Retrieving User Details From a Token

若你已經擁有使用者的有效 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);

If you are using Facebook Limited Login via an iOS application, Facebook will return an OIDC token instead of an access token. Like an access token, the OIDC token can be provided to the userFromToken method in order to retrieve user details.

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