OIDC by Jefferson Gonçalves

• Compatibility
• Installation
• Registering the plugin in a panel
• Multi-panel setup
• Linking identities to users
• Customising user provisioning
• Logout (RP-initiated)
• Events
• Testing
• Changelog
• Security Vulnerabilities
• Credits
• License

Drop-in OpenID Connect single sign-on for Filament v5 panels, powered by jeffersongoncalves/laravel-oidc. Works in single- and multi-panel apps, supports per-panel guards, and stores OIDC identities in a polymorphic table so the host application's users table is never altered.

#Compatibility

Releases v1.0.0 and 1.1.0 were published for Filament v5 before the plugin adopted the branch-per-Filament-major layout. Filament v5 users should require ^3.0.

#Installation

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

Publish and run the migration that creates the oidc_identities table (shipped by jeffersongoncalves/laravel-oidc):

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

Optionally publish the configuration and translations:

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

Configure the underlying laravel-oidc driver via the standard environment variables:

OIDC_ISSUER_URL=https://idp.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

The plugin computes the redirect URI from the panel route, so you do not need to set OIDC_REDIRECT_URI. Register https://your-app.test/{panel}/oidc/callback with your Identity Provider for every panel that exposes the plugin.

#Registering the plugin in a panel

use JeffersonGoncalves\Filament\Oidc\FilamentOidcPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->login()
        ->plugin(
            FilamentOidcPlugin::make()
                ->guard('web')
                ->autoCreateUsers(true)
        );
}

#Multi-panel setup

Register the plugin once per panel. Each panel gets its own routes (filament.{panel-id}.oidc.{redirect|callback|logout}), its own callback URL, and may opt into a different guard or user model.

// AdminPanelProvider
$panel->plugin(
    FilamentOidcPlugin::make()
        ->guard('web')
        ->userModel(\App\Models\User::class)
);

// CustomerPanelProvider
$panel->plugin(
    FilamentOidcPlugin::make()
        ->guard('customer')
        ->userModel(\App\Models\Customer::class)
        ->autoCreateUsers(false)
);

Register the per-panel callback URL with your IdP:

https://your-app.test/admin/oidc/callback
https://your-app.test/customer/oidc/callback

#Linking identities to users

The plugin stores every IdP/subject pair in the oidc_identities table (the OidcIdentity model from laravel-oidc; table name set by oidc.identities_table) and links it to the authenticated model through a polymorphic relationship. Add the HasOidcIdentities trait to expose the oidcIdentities() relation on your authenticatable model:

use JeffersonGoncalves\LaravelOidc\Concerns\HasOidcIdentities;

class User extends Authenticatable
{
    use HasOidcIdentities;
}

The default callback handler:

1. Looks up oidc_identities.{issuer, subject}.
2. Falls back to matching the local user by email.
3. Creates a new user when auto_create_users is enabled, otherwise throws OidcAuthenticationException::autoCreateDisabled().

#Customising user provisioning

Override either the attribute mapping or the full resolution closure:

FilamentOidcPlugin::make()
    ->userAttributesUsing(fn (\Laravel\Socialite\Two\User $oidcUser) => [
        'name' => $oidcUser->getName(),
        'email' => $oidcUser->getEmail(),
        'tenant_id' => $oidcUser->user['tenant'] ?? null,
        'password' => bcrypt(\Illuminate\Support\Str::random(40)),
    ])
    ->resolveUserUsing(function (\App\Models\User $template, \Laravel\Socialite\Two\User $oidcUser) {
        return \App\Models\User::query()->updateOrCreate(
            ['email' => $oidcUser->getEmail()],
            ['name' => $oidcUser->getName()],
        );
    });

#Logout (RP-initiated)

Enable IdP logout to redirect users to the issuer's end_session_endpoint after the local logout completes:

FilamentOidcPlugin::make()->logoutFromIdp(true);

Use the named route from your blade templates (e.g. inside a custom user menu):

<form method="POST" action="{{ route('filament.admin.oidc.logout') }}">
    @csrf
    <button type="submit">Log out</button>
</form>

#Events

#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

• Jefferson Gonçalves

#License

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