Laravel Socialite は、開(kāi)発者がアプリケーションに OAuth および OAuth2 ソーシャル認(rèn)証を?qū)g裝するのに役立つファーストパーティの Laravel パッケージです。 Facebook、Twitter、Google、LinkedIn、GitHub、GitLab、Bitbucket のサポートが組み込まれています。 Socialite は、コミュニティ パッケージを通じて他のプロバイダーをサポートできます。

この投稿は次の內(nèi)容になります:

• Socialite が行うことと行わないことを説明します。
• Socialite を介して Google 認(rèn)証を新しい Laravel プロジェクトに統(tǒng)合する方法を示します。
• Socialite のテスト例を示します。

TLDR: 完成したプロジェクトは私の GitHub でご覧いただけます。完成したコードを読むだけなら、ぜひ見(jiàn)てください。

Laravel Socialite は何をし、何をしませんか?

Socialite は小さなパッケージであり、そのメイン API は主に 2 つの主要なメソッドで構(gòu)成されています。

• Socialite::driver($authProvider)->redirect() は、ユーザーを指定された認(rèn)証プロバイダーにリダイレクトし、必要な情報(bào)を URL パラメーター経由でプロバイダーに渡します。
• Socialite::driver($authProvider)->user() は、認(rèn)証プロバイダーから返されたユーザー データを取得し、エンドポイントで利用できるようにします。

スコープとオプションのパラメーターを設(shè)定するための追加のサポート方法があります。これらについては、Socialite のドキュメントで読むことができます。

Socialite は次のことをしません: これらの機(jī)能の実裝は開(kāi)発者に任されています:

• ? ソーシャル認(rèn)証データを保存するために必要なデータベース テーブルまたは列を作成します。
• ? 認(rèn)証プロセス中に存在しないユーザーを作成します。
• ? OAuth フローが成功した後にユーザーを認(rèn)証します。
• ? OAuth トークンを更新します。

前提條件: Google Cloud プロジェクトの作成

ユーザーが Google 経由で認(rèn)証できるようにする小規(guī)模な Socialite プロジェクトをセットアップします。そのためには、Google アプリを作成する必要があります。

まず新しい Google Cloud プロジェクトを作成し、次にプロジェクトの OAuth 同意畫面を構(gòu)成します。 ユーザー タイプを外部に設(shè)定し、次のスコープを有効にします:

• .../auth/userinfo.email
• .../auth/userinfo.profile

同意畫面を設(shè)定した後、Google Cloud 認(rèn)証情報(bào)ページにアクセスして OAuth 2.0 クライアント ID を作成します。 クライアント ID と クライアント シークレット を保管しておいてください。これらはプロジェクトの後半で使用します。

Socialite を使用した最小限の Laravel プロジェクトのセットアップ

新しい Laravel プロジェクトを作成します:

laravel new socialite-tests

インストーラーから次のオプションを選択します:

 ┌ Would you like to install a starter kit? ────────────────────┐
 │ No starter kit                                               │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which testing framework do you prefer? ──────────────────────┐
 │ Pest                                                         │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which database will your application use? ───────────────────┐
 │ SQLite                                                       │
 └──────────────────────────────────────────────────────────────┘

 ┌ Would you like to run the default database migrations? ──────┐
 │ Yes                                                          │
 └──────────────────────────────────────────────────────────────┘

プロジェクト ディレクトリに移動(dòng)し、Socialite をインストールします。

laravel new socialite-tests

新しい移行を作成します。

 ┌ Would you like to install a starter kit? ────────────────────┐
 │ No starter kit                                               │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which testing framework do you prefer? ──────────────────────┐
 │ Pest                                                         │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which database will your application use? ───────────────────┐
 │ SQLite                                                       │
 └──────────────────────────────────────────────────────────────┘

 ┌ Would you like to run the default database migrations? ──────┐
 │ Yes                                                          │
 └──────────────────────────────────────────────────────────────┘

database/migrations に新しく作成した移行ファイルに次のコードを配置します。

cd socialite-tests
composer require laravel/socialite

この移行により、ユーザーが認(rèn)証に成功したときに Socialite によって提供されるフィールドが追加されます。私たちの実裝では、簡(jiǎn)単にするためにこれらのフィールドをユーザー テーブルに直接追加しています。 Google よりも多くのプロバイダーをサポートしたい場(chǎng)合は、ユーザーごとに複數(shù)のプロバイダーを保存できる別のテーブルを作成するとよいでしょう。

Google 経由でのみ認(rèn)証する場(chǎng)合、ユーザーは決してパスワードを設(shè)定しないため、パスワードを null 可能に設(shè)定しています。アプリでソーシャル認(rèn)証とパスワード認(rèn)証が許可されている場(chǎng)合、ユーザーがパスワードを使用してログインしようとするときに、パスワードが空白または null でないことを検証する必要があります。

移行を?qū)g行します。

php artisan make:migration add_socialite_fields_to_users

config/services.php で、次のコード ブロックを services 配列の最後に追加します。有効な Socialite サービス名の完全なリストは、構(gòu)成ドキュメントで確認(rèn)できます。

<?php
// database/migrations/2024_12_31_075619_add_socialite_fields_to_users.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('google_id')->default('');
            $table->string('google_token')->default('');
            $table->string('google_refresh_token')->default('');

            // If your app allows both password and social logins, you
            // MUST validate that the password is not blank during login.
            // If you do not, an attacker could gain access to an account
            // that uses social login by only knowing the email.
            $table->string('password')->nullable()->change();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('google_id');
            $table->dropColumn('google_token');
            $table->dropColumn('google_refresh_token');
            $table->string('password')->nullable(false)->change();
        });
    }
};

「前提條件」セクションで作成した Google アプリの認(rèn)証情報(bào)を使用して、以下を .env に追加します。

php artisan migrate

routes/web.php の內(nèi)容を次のコードに置き換えます。

// config/services.php

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => '/auth/google/callback',
],

このファイルの新しいコードは次のルートを?qū)g裝します:

適切な情報(bào)を使用してソーシャル ログインのために Google にリダイレクトします。
Google からのコールバックを処理します。このルートは、ログイン時(shí)にユーザーを作成または更新し、認(rèn)証してホームページにリダイレクトします。
認(rèn)証されたユーザーをログアウトします。

最後に、resources/views/welcome.php の內(nèi)容を次のマークアップで置き換えます。

# .env

GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

これが完了したら、開(kāi)発サーバーを?qū)g行してアプリを手動(dòng)でテストできます。

<?php
// routes/web.php

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Route;
use Laravel\Socialite\Facades\Socialite;
use Laravel\Socialite\Two\InvalidStateException;
use Laravel\Socialite\Two\User as OAuth2User;

Route::get('/', function () {
    return view('welcome');
});

Route::get('/auth/google/redirect', function () {
    return Socialite::driver('google')->redirect();
});

Route::get('/auth/google/callback', function () {
    try {
        /** @var OAuth2User $google_user */
        $google_user = Socialite::driver('google')->user();
    } catch (InvalidStateException $exception) {
        abort(400, $exception->getMessage());
    }

    $user = User::updateOrCreate([
        'email' => $google_user->email,
    ], [
        'google_id' => $google_user->id,
        'name' => $google_user->name,
        'google_token' => $google_user->token,
        'google_refresh_token' => $google_user->refreshToken,
    ]);

    Auth::login($user);
    return redirect('/');
});

Route::get('/auth/logout', function () {
    Auth::logout();
    return redirect('/');
});

Google でログイン リンクをクリックすると、OAuth2 フローが実行され、ホームページにリダイレクトされ、Google から新しく作成されたユーザーに関する情報(bào)が表示されます。

社交界の人々を害蟲でテストする

私たちの手動(dòng)テストは

機(jī)能しますが、將來(lái)この機(jī)能を誤って壊さないことを確認(rèn)するために自動(dòng)テストを希望します。

次のコマンドを使用して、新しいテスト ファイルを作成できます。

<!-- resources/views/welcome.php -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Laravel Socialite Testing Example</title>
</head>
<body>
    <h1>Laravel Socialite Testing Example</h1>
    @if (auth()->check())
        <p>User is authenticated.</p>
        <p>Name: {{ auth()->user()->name }}</p>
        <p>Email: {{ auth()->user()->email }}</p>
        <p><a href="/auth/logout">Logout</a></p>
    @else
        <p>User is not authenticated.</p>
        <p>
            <a href="/auth/google/redirect">Login with Google</a>
        </p>
    @endif
</body>
</html>

新しく作成したtests/Feature/AuthRoutesTest.phpの內(nèi)容を次のものに置き換えます。

php artisan serve

テストの仕組み

リダイレクト ルートをテストするときは、Socialite が正しい URL にリダイレクトし、正しい URL パラメーターを渡すことをテストします。

コールバック ルートをテストするとき、Socialite を模擬します。モッキングは私の好みのオプションではありません。理想的な世界では、Socialite を別の OAuth2 実裝に置き換えることができ、テストは引き続き機(jī)能します。ただし、アクセス トークンを追加するために Socialite が送信する認(rèn)可付與リクエストに接続する簡(jiǎn)単な方法はありません。このため、モックは Socialite をテストするための最も現(xiàn)実的なアプローチです。

Fluent API を Mockery 経由でモックするには面倒です。終了呼び出しから開(kāi)始して、逆方向に作業(yè)する必要があります。

これは、コールバック エンドポイントが呼び出す Socialite メソッドです。

laravel new socialite-tests

Mockery を介してこれを嘲笑する方法は次のとおりです:

 ┌ Would you like to install a starter kit? ────────────────────┐
 │ No starter kit                                               │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which testing framework do you prefer? ──────────────────────┐
 │ Pest                                                         │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which database will your application use? ───────────────────┐
 │ SQLite                                                       │
 └──────────────────────────────────────────────────────────────┘

 ┌ Would you like to run the default database migrations? ──────┐
 │ Yes                                                          │
 └──────────────────────────────────────────────────────────────┘

最後に、OAuth フローの外部でコールバック URL に直接移動(dòng)すると 400 ステータス コードが返されることを確認(rèn)するテストがあります。 Socialite::driver('google')->user() への呼び出しを try/catch ブロック內(nèi)のコールバック エンドポイントにラップしました。 Socialite 呼び出しを try/catch ブロックでラップしておらず、誰(shuí)かがブラウザにコールバック URL を入力した場(chǎng)合、エンドポイントは HTTP 500 ステータス コードの例外をスローします。チームが 500 ステータス コードの監(jiān)視を設(shè)定している場(chǎng)合、深夜に誰(shuí)かにページングが行われる可能性があります。

まとめ

これは最小限の統(tǒng)合であり、他にも実裝できるものはたくさんあります。ユーザーの電子メールが変更される可能性があるソーシャル プロバイダーとの統(tǒng)合を?qū)g裝している場(chǎng)合、電子メール アドレスと一致するため、この実裝は機(jī)能しません。ユーザーがアプリ內(nèi)でメール アドレスを変更できる場(chǎng)合、この実裝も同じ理由で機(jī)能しません。ただし、Socialite をテストする方法を理解したので、これらのシナリオのテストを作成し、それらが合格するように基礎(chǔ)となる実裝を変更できます。

獨(dú)自の実裝の構(gòu)築方法、テスト方法、何を考慮する必要があるかを理解する前に、Socialite に関するブログ記事やフォーラムの投稿をたくさん読みました。ここでその一部について謝意を表したいと思います。

• Stefan Zweifel による Laravel Socialite 搭載アプリの統(tǒng)合テストの書き方
• ServerSideUp フォーラム: ソーシャライトのベスト プラクティス、會(huì)話
• スタック オーバーフロー: Laravel ソーシャルライトをテストする方法
• スタック交換: ソーシャル ログインを一致する電子メールにリンクするかどうか
• スタック交換: 接続されたソーシャル アカウントと潛在的な孤立者への対処

さらに詳しく知りたい場(chǎng)合は、これらをお読みください。また、複數(shù)のソーシャル プロバイダーの処理、ユーザーがメール アドレスを変更したときの処理、または更新トークンの処理について詳しく説明するこの投稿のパート 2 に興味がある場(chǎng)合はお知らせください。

以上がLaravel での Socialite 認(rèn)証の実裝とテストの詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國(guó)語(yǔ) Web サイトの他の関連記事を參照してください。