README

Laravel Socialite

UI-agnostic building blocks on top of Laravel Socialite: a fluent provider definition, user resolution/registration and a social_accounts table linking OAuth identities to your users. Bring your own routes and views, or use Filament Socialite for Filament panels.

Supports PHP 8.1+ and Laravel 10 to 13.

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-socialite

Publish and run the migration (optional, see socialAccounts below):

php artisan vendor:publish --tag="socialite-migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag="socialite-config"

Add each provider's credentials to config/services.php as usual for Socialite. The redirect key is required by Socialite, but you can pass the callback URL at runtime instead:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => null,
],

Usage

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use JeffersonGoncalves\Socialite\Provider;
use JeffersonGoncalves\Socialite\SocialiteUserResolver;

$github = Provider::make('github')
    ->scopes(['read:user', 'user:email'])
    ->with(['allow_signup' => 'false']);

// Redirect
Route::get('/oauth/github', fn () => $github->driver(route('oauth.callback'))->redirect());

// Callback
Route::get('/oauth/github/callback', function () use ($github) {
    $oauthUser = $github->driver(route('oauth.callback'))->user();

    $resolver = new SocialiteUserResolver(User::class, registrationEnabled: true);

    $user = $resolver->resolve($github, $oauthUser) ?? abort(403);
    $resolver->link($user, $github, $oauthUser);

    Auth::login($user, remember: true);

    return redirect()->intended('/dashboard');
})->name('oauth.callback');

Provider

Method	Description
`scopes(array)`	Extra OAuth scopes.
`with(array)`	Extra query parameters for the authorization request.
`stateless(bool)`	Disable session state verification (APIs/SPAs only).
`driver(?string $redirectUrl)`	The configured Socialite driver.

Provider is meant to be extended by UI layers (labels, icons, colors). Any Socialite driver works, including Socialite Providers.

SocialiteUserResolver

new SocialiteUserResolver(
    userModel: User::class,
    socialAccounts: true,          // look up and store links in social_accounts
    registrationEnabled: false,    // create a user when nothing matches
    resolveUserUsing: null,        // fn (SocialiteUser $user, Provider $provider): ?Model — replaces the lookup
    createUserUsing: null,         // fn (SocialiteUser $user, Provider $provider): ?Model — custom registration
);

resolve() looks up, in order:

resolveUserUsing, if set, decides alone.
A linked row in social_accounts (provider + provider id).
A user with the same email.
If registration is enabled: createUserUsing or a default name/email/random password user.

link() stores or updates the social account with the OAuth tokens (encrypted at rest). It does nothing when socialAccounts is false.

Security: step 3 trusts the email returned by the provider. Only enable providers that verify emails, or use resolveUserUsing to add your own checks.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

jeffersongoncalves / laravel-socialite

Package info

Security

Fund package maintenance!

Statistics