Filament Socialite

#Filament Socialite

OAuth login for Filament panels powered by Laravel Socialite: a fluent provider API, buttons injected into the login page, and optional linked social accounts.

#Compatibility

Package Version	Filament Version
1.x	3.x
2.x	4.x
3.x	5.x

#Installation

You can install the package via composer:

composer require jeffersongoncalves/filament-socialite:"^3.0"

User resolution, the social_accounts table and the base Provider come from jeffersongoncalves/laravel-socialite, installed automatically.

Publish and run the migration (skip it if you only want to match users by email, see socialAccounts(false) below):

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

Optionally publish the config and translations:

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

#Configuring providers

Add each provider's credentials to config/services.php. The redirect key is required by Socialite but its value is ignored: the plugin always uses its own callback route.

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

Register the callback URL in the provider's dashboard: https://your-app.test/{panel-path}/oauth/{provider}/callback, e.g. https://your-app.test/admin/oauth/github/callback.

#Usage

use JeffersonGoncalves\Filament\Socialite\Provider;
use JeffersonGoncalves\Filament\Socialite\SocialitePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->login()
        ->plugin(
            SocialitePlugin::make()
                ->providers([
                    Provider::make('github')
                        ->label('GitHub')
                        ->icon('heroicon-o-code-bracket')
                        ->color('gray')
                        ->scopes(['read:user', 'user:email']),
                    Provider::make('google')
                        ->label('Google')
                        ->color('danger')
                        ->with(['prompt' => 'select_account']),
                ])
                ->registrationEnabled(),
        );
}

#Provider options

Method	Description
`label(string)`	Button label (defaults to the headline of the driver name).
`icon(string)`	Any Blade Icons name installed in your app (e.g. `heroicon-o-user`, `fab-github` with a Font Awesome icon set).
`color(string)`	Filament color (`gray`, `primary`, `danger`, ...).
`scopes(array)`	Extra OAuth scopes.
`with(array)`	Extra query parameters for the authorization request.
`stateless(bool)`	Disable session state verification (APIs/SPAs only).

Any Socialite driver works, including Socialite Providers once registered.

#Plugin options

Method	Default	Description
`registrationEnabled(bool)`	`false`	Create a user when no account matches.
`createUserUsing(Closure)`	`null`	Custom user creation: `fn (SocialiteUser $user, Provider $provider): ?Model`.
`resolveUserUsing(Closure)`	`null`	Replace the whole lookup: `fn (SocialiteUser $user, Provider $provider): ?Model`.
`socialAccounts(bool)`	`true`	Store logins in the `social_accounts` table. With `false`, users are only matched by email.
`slug(string)`	`oauth`	Route prefix: `/{panel}/{slug}/{provider}/redirect\|callback`.
`renderHook(string)`	`PanelsRenderHook::AUTH_LOGIN_FORM_AFTER`	Where the buttons are rendered.

#How users are resolved

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

After login the social account is linked (tokens are stored encrypted). Users implementing FilamentUser must pass canAccessPanel(). Failures send the user back to the login page with a notification.

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

#Outside Filament

Need the same login flow in a non-Filament app (Blade, Inertia, API)? Use jeffersongoncalves/laravel-socialite directly.

#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.