Implementing & testing Socialite authentication in Laravel

Laravel Socialite is a first-party Laravel package that helps developers implement OAuth & OAuth2 social authentication in their applications. It has built-in support for Facebook, Twitter, Google, LinkedIn, GitHub, GitLab, and Bitbucket. Socialite can support other providers through community packages.

This post will:

• Explain what Socialite does and does not do.
• Show how to integrate Google authentication into a new Laravel project via Socialite.
• Show an example of testing Socialite.

TLDR: you can view the completed project on my GitHub. Take a look at it if you would rather just read the completed code.

What does Laravel Socialite do and not do?

Socialite is a small package, with its main API primarily consisting of two main methods:

• Socialite::driver($authProvider)->redirect() will redirect the user to the specified auth provider, passing any necessary information to the provider via URL parameters.
• Socialite::driver($authProvider)->user() retrieves user data passed back from the auth provider and makes it available to the endpoint.

There are additional support methods for settings scopes and optional parameters. You can read about them in the Socialite documentation.

Socialite does not do the following: it leaves the implementation of these features up to the developer:

• ❌ Create database tables or columns needed to store social auth data.
• ❌ Create users that don't exist during the authentication process.
• ❌ Authenticate the user after a successful OAuth flow.
• ❌ Refresh OAuth tokens.

Prerequisites: creating a Google Cloud project

We will set up a small Socialite project that allows the user to authenticate via Google. To do that, you must create a Google app.

First create a new Google Cloud project, then configure an OAuth consent screen for the project. Set the user type to external, then enable the following scopes:

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

After configuring the consent screen, create an OAuth 2.0 Client ID by visiting the Google Cloud Credentials Page. Hold on to the client ID and client secret: we will use them later in the project.

Setting up a minimal Laravel project with Socialite

Create a new Laravel project:

laravel new socialite-tests

Select the following options from the installer:

 ┌ 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                                                          │
 └──────────────────────────────────────────────────────────────┘

Change into the project directory and install Socialite.

cd socialite-tests
composer require laravel/socialite

Create a new migration.

php artisan make:migration add_socialite_fields_to_users

Place the following code in the newly created migration file in database/migrations:

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

This migration adds fields that will be provided by Socialite when the user successfully authenticates. In our implementation we're adding these fields directly onto the user table for simplicity. If you wanted to support more providers than Google, you may want to create a separate table that could store multiple providers per user.

We're setting the password to be nullable because a user will never set a password if they only authenticate via Google. If your app permits social authentication and password authentication, you must validate that the password is not blank or null when a user attempts to login via a password.

Run the migration.

php artisan migrate

In config/services.php, add the following block of code to the end of the services array. You can find a full list of valid Socialite service names in the configuration docs.

// config/services.php

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

Add the following to .env, using the credentials from your Google app that you created in the "prerequisites" section.

# .env

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

Replace the contents of routes/web.php with the following code.

<?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('/');
});

The new code in this file implements the routes for:

• Redirecting to Google for social login with the appropriate information.
• Handling the callback from Google. This route creates or updates a user upon login, then authenticates them, and redirects them to the homepage.
• Logging out an authenticated user.

Finally, replace the contents of resources/views/welcome.php with the following markup.

<!-- 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>

With this completed, we can manually test the app by running the development server.

php artisan serve

When you click the Login with Google link, you should go through the OAuth2 flow and be redirected to the homepage where you can see information about the newly created user from Google.

Testing Socialite with Pest

Our manual tests work, but we'd like automated tests to verify that we don't accidentally break this functionality in the future.

We can create a new test file with the following command.

php artisan make:test AuthRoutesTest

Replace the contents of the newly created tests/Feature/AuthRoutesTest.php with the following.

<?php
// tests/Feature/AuthRoutesTest.php

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Laravel\Socialite\Contracts\Provider as SocialiteProvider;
use Laravel\Socialite\Facades\Socialite;
use Laravel\Socialite\Two\User as OAuth2User;
use Illuminate\Support\Facades\Auth;

use function Pest\Laravel\assertAuthenticated;
use function Pest\Laravel\assertGuest;
use function Pest\Laravel\get;

uses(RefreshDatabase::class);

describe('authentication routes', function () {
    it('redirects login route to correct Google URL', function () {
        $response = get('/auth/google/redirect');

        $redirect_url = $response->getTargetUrl();
        $parsed_query = []; // passed by reference to parse_str()
        parse_str(parse_url($redirect_url)['query'] ?? '', $parsed_query);

        $response->assertStatus(302);
        expect($redirect_url)->toStartWith(
            'https://accounts.google.com/o/oauth2/auth'
        );
        expect($parsed_query)->toHaveKeys([
            'client_id',
            'redirect_uri',
            'scope',
            'response_type',
            'state'
        ]);
    });

    it('creates and authenticates a user that does not yet exist', function () {
        $oauth_user = new OAuth2User();
        $oauth_user->id = '12345';
        $oauth_user->name = 'Tyler Smith';
        $oauth_user->email = '[e-mail]';
        $oauth_user->token = '123456789abcdef';
        $oauth_user->refreshToken = '123456789abcdef';

        $mock_provider = Mockery::mock(SocialiteProvider::class);
        $mock_provider->shouldReceive('user')->andReturn($oauth_user);
        Socialite::shouldReceive('driver')
            ->with('google')
            ->andReturn($mock_provider);

        get('/auth/google/callback');

        assertAuthenticated();
        expect(User::count())->toBe(1);
        expect(Auth::user()->email)->toBe($oauth_user->email);
    });

    it('authenticates an existing user', function () {
        $oauth_user = new OAuth2User();
        $oauth_user->id = '12345';
        $oauth_user->name = 'Tyler Smith';
        $oauth_user->email = '[e-mail]';
        $oauth_user->token = '123456789abcdef';
        $oauth_user->refreshToken = '123456789abcdef';

        $app_user = User::factory()->create([
            'email' => $oauth_user->email,
        ]);

        $mock_provider = Mockery::mock(SocialiteProvider::class);
        $mock_provider->shouldReceive('user')->andReturn($oauth_user);
        Socialite::shouldReceive('driver')
            ->with('google')
            ->andReturn($mock_provider);

        get('/auth/google/callback');

        assertAuthenticated();
        expect(User::count())->toBe(1);
        expect(Auth::id())->toBe($app_user->id);
    });

    it('redirects authenticated user to the homepage', function () {
        $oauth_user = new OAuth2User();
        $oauth_user->id = '12345';
        $oauth_user->name = 'Tyler Smith';
        $oauth_user->email = '[e-mail]';
        $oauth_user->token = '123456789abcdef';
        $oauth_user->refreshToken = '123456789abcdef';

        $mock_provider = Mockery::mock(SocialiteProvider::class);
        $mock_provider->shouldReceive('user')->andReturn($oauth_user);
        Socialite::shouldReceive('driver')
            ->with('google')
            ->andReturn($mock_provider);

        $response = get('/auth/google/callback');

        assertAuthenticated();
        $response->assertRedirect('/');
    });

    it('returns 400 when the oauth callback url is requested directly', function () {
        $response = get('/auth/google/callback');

        $response->assertStatus(400);
        assertGuest();
    });
});

How the tests work

When testing the redirect route, we test that Socialite redirects to the correct URL and passes the correct URL parameters.

When testing the callback routes, we mock Socialite. Mocking isn't my favorite option: in an ideal world, we could swap out Socialite for another OAuth2 implementation and our tests would still work. However, there's not a straight forward way to hook into the authorization grant request that Socialite sends to garnish the access token. Because of this, mocking is the most practical approach to testing Socialite.

Fluent APIs are tedious to mock via Mockery: you must start from the end call and work your way backwards.

Here is the Socialite method that our callback endpoint invokes.

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

Here is how that must be mocked via Mockery:

// Mock ->user();
$mock_provider = Mockery::mock(SocialiteProvider::class);
$mock_provider->shouldReceive('user')->andReturn($oauth_user);

// Mock Socialite::driver('google')
Socialite::shouldReceive('driver')
    ->with('google')
    ->andReturn($mock_provider);

Finally, we have a test to ensure that navigating directly to the callback URL outside of the OAuth flow returns a 400 status code. We wrapped the call to Socialite::driver('google')->user() in the callback endpoint within a try/catch block. If we hadn't wrapped the Socialite call in a try/catch block and someone typed the callback URL into their browser, the endpoint would throw an exception with an HTTP 500 status code. If your team has monitoring set up for 500 status codes, that could cause someone to get paged in the middle of the night.

Wrapping up

This is a minimal integration, and there's a lot more that could be implemented. If we were implementing an integration with a social provider where the user's email could change, this implementation wouldn't work since it matches against the email address. If the user could change their email address within our app, this implementation also wouldn't work for the same reason. However, now that you've seen how to test Socialite, you could write tests for these scenarios and modify the underlying implementation so that they pass.

I read a lot of blog articles and forum posts about Socialite before I understood how to build my own implementation, how to test it, and what I should think about. I'd like to acknowledge some of those here.

• How I write integration tests for Laravel Socialite powered apps by Stefan Zweifel
• ServerSideUp forum: Socialite Best Practices, a conversation
• Stack Overflow: How to Test Laravel Socialite
• Stack Exchange: To Link or Not to Link Social Logins with a Matching Email
• Stack Exchange: Dealing with Connected Social Accounts and Potential Orphans

Read those if you're interested in digging deeper. Also, let me know if you'd be interested in a part 2 of this post where I dig into handling multiple social providers, handling when a user changes their email address, or handling refresh tokens.