Filament Oauth2 Laravel Package

Getting Started

Install and register

composer require alexandergabriel/filament-oauth2
php artisan vendor:publish --tag="filament-oauth2-config"
php artisan vendor:publish --tag="filament-oauth2-migrations"   # if prompted
php artisan migrate

Add the plugin to the panel you want to expose OAuth on:

use AlexanderGabriel\FilamentOAuth2\FilamentOAuth2Plugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentOAuth2Plugin::make());
}

Then configure your providers in config/filament-oauth2.php and put the matching credentials in config/services.php (the package leans on Laravel Socialite under the hood). Clear caches after the first setup: php artisan config:clear && php artisan route:clear && php artisan view:clear.

Where to look first

1. The published config/filament-oauth2.php — it is the source of truth for enabled providers, scopes, redirect behaviour and how OAuth identities are matched to local users.
2. The plugin class itself — read register()/boot() to see which login page and routes it swaps in.
3. The published views, if you need to restyle the buttons or change the layout of the login form.

First use case

The 15-minute win is replacing the stock Filament login with "Continue with GitHub/Google/Microsoft" for an internal panel. Register one provider, point the callback at https://your-app.test/oauth2/callback/{provider} (verify the exact path in the package routes — php artisan route:list | grep -i oauth), and confirm a brand-new OAuth user lands on the dashboard. Once that works, layer password login back in for break-glass admin access.

Implementation Patterns

Keep password login alongside OAuth. Most teams don't want to remove the email/password form. Two viable approaches:

• Keep Filament's default Login page and render the package's buttons through a render hook, e.g. PanelsRenderHook::AUTH_LOGIN_FORM_AFTER, so users get both options on one screen.
• Use the package's login page and add a "sign in with password" link back to the standard route.

Decide this early — it affects whether you subclass Filament\Auth\Pages\Login or just hook the view.

Account linking for existing users. The valuable flow isn't first login, it's the second one: an existing user who signed up with a password wants to add Google. Expose connect/disconnect actions on the profile page (a Filament Action that hits the redirect route for the provider), and make sure your filament-oauth2 config allows linking to an already-authenticated user rather than only creating new ones. Store the provider identity keyed by (provider, provider_id) with a unique index — do not key on email.

Config-driven provider rollout. Treat filament-oauth2.php as environment-aware: enable Google in production, enable a dev-only provider in local. Read the provider list from config rather than hardcoding buttons, so adding Microsoft later is a config change plus services.php credentials, not a code change.

Multi-panel / multi-guard setups. If you run an admin panel and a customer panel, register the plugin per panel and be explicit about which guard and user model each uses. The callback route is shared, so disambiguate by panel or by provider config — otherwise an admin OAuth login can complete against the customer guard. Also confirm the session cookie domain covers all panels and subdomains, or the state check will fail intermittently.

Mapping to local users. Decide and document the policy: match on verified email, or require an explicit link step. A sensible default is: if the provider returns a verified email that matches an existing user, link automatically; otherwise create a new user with a random password and no roles. Assign roles/spatie permissions in a User created-observer or a package callback, not in the login page.

Testing. Use Http::fake() around the provider token/user endpoints, or Laravel's Socialite::fake() where available, and assert the redirect → callback → authenticated round trip. Also test the failure path: user denies consent, state mismatch, provider returns no email. Those are the paths that break silently in production.

Gotchas and Tips

This is a 1.x → 2.x jump — treat it as breaking. The changelog diff is a major version bump, not a patch. Before upgrading:

• Check the Filament major version the release targets (plugin asset/namespace and page-class changes typically accompany a Filament major bump).
• Re-publish the config and views (--force) and diff them against yours; config keys are the most common thing to be renamed.
• Re-run php artisan filament:assets / rebuild assets if the package ships any.
• Pin the version in composer.json and test the callback route end-to-end in staging — a broken callback is a total login outage for OAuth users.
• If you have custom subclasses of the package's login page, verify the parent class signature hasn't changed.

Callback URL mismatches are the #1 support ticket. The exact scheme, host, port and path registered with the provider must match what the app generates. Behind a load balancer or Heroku-style proxy, set TrustProxies correctly and confirm APP_URL is the public URL, or you'll get redirect_uri_mismatch from the provider while everything looks fine locally.

Never trust an unverified email. Some providers return an email that isn't verified, and some return none at all (GitHub requires the user:email scope and a separate /user/emails call to get the primary verified address). Auto-linking by email without a verified flag is an account-takeover vector. Gate linking behind the provider's email_verified claim.

Session and state errors. InvalidStateException almost always means the session didn't survive the redirect: cookie domain, SESSION_DOMAIN, SameSite=None requirements for the provider's redirect back into an iframe, or the user started login in one tab and finished in another. It also appears when config:cache was run before the config file was published.

Cache and route quirks. After editing provider config, config:clear is mandatory — cached config silently ignores new providers. If you're using route:cache in production, confirm the callback route is cacheable (it should be a GET route without a closure) and rebuild.

Provider-specific quirks worth knowing. Microsoft/Azure requires the tenant in the authorize URL; Google needs the right scopes if you want refresh tokens; GitHub returns no email by default. Keep per-provider scope overrides in config rather than in code.

Extension points if you outgrow the defaults. The package delegates to Socialite, so Socialite::extend() / Socialite::driver() custom providers work normally. For anything the plugin doesn't expose — custom user provisioning, extra claims, tenant resolution — prefer overriding via the config callbacks or a small service class over forking; forks of a 2.x-just-released plugin age badly.

Debugging checklist. php artisan route:list | grep oauth2 to confirm routes exist; log the Socialite exception in the failed-callback handler (the package swallows it into a notification by default); check storage/logs/laravel.log for Laravel\Socialite\Two\InvalidStateException; and reproduce with the provider's own OAuth playground to isolate whether it's your app or the provider config.