Filament Okta Laravel Package

Getting Started

1. composer require bbs-lab/laravel-okta (v3.x) and publish the config so you get the per-panel block (filament-okta.{panel}.*).
2. In the Okta admin console, register an OIDC app with:
   • Sign-in redirect URI: {panel-path}/authorization-code/callback
   • Sign-out redirect URI: {panel-path}/authorization-code/logout ← the v3.0.0 default, not the v2 …/callback/logout
3. Attach the plugin in your panel provider: ->plugin(OktaPlugin::make()), then fill in the panel's Okta credentials/config.
4. First use case worth building: gate an internal Filament panel behind Okta SSO so you inherit your org's MFA, session policy, and deprovisioning instead of maintaining passwords and a login form.

Look first at: the published config file (it is per-panel, keyed by panel id), php artisan route:list --name=filament-okta, and OktaPlugin::paths() if you need non-standard endpoints. A single-panel app is ~15 minutes of work; the interesting complexity is all in multi-panel setups and logout.

Implementation Patterns

Per-panel configuration. Each Filament panel gets its own config block and therefore its own Okta app (or at least its own redirect URIs). This is the intended shape for admin + portal style apps: different Okta apps, different group policies, one package.

Logout. Never link to a literal path — use route('filament-okta.{panel}.logout'). Route names are stable across v2 → v3, which is exactly why the v3 change is easy to miss: the name resolves to a different URI now (…/logout/redirect, which then hands off to Okta's end-session endpoint and lands back on …/logout).

Overriding paths. OktaPlugin::make()->paths(logout: '…', callbackLogout: '…'). Read the semantics carefully in v3:

• callbackLogout: → the landing page after Okta signs the user out (default {panel-path}/authorization-code/logout)
• logout: → the initiator route (default {panel-path}/authorization-code/logout/redirect)

The argument names are unchanged from v2 but the meanings swapped roles. Any explicit override in your codebase needs a re-read, not just the defaults.

Authorization. Map Okta group claims onto your User model and enforce panel access in canAccessPanel(). That keeps the package doing authentication only and puts authorization where Filament expects it.

Local development and tests. Keep a non-Okta path into the panel (seeded user + a dev-only guard switch) so you aren't blocked when Okta is unreachable or your test app is misconfigured. In Pest, assert against route names and fake the outbound Okta HTTP calls; the package's own suite runs at 100% coverage / 100% MSI with PHPStan level 8, so it is safe to be strict on your side too.

Deployment. Add the new sign-out redirect URI in Okta before rolling v3 out, and keep the old one whitelisted until every environment is on v3. Sign-in is untouched, so a partially migrated fleet still lets people in — they just fail on the way out.

Gotchas and Tips

• The v3.0.0 change is logout-only, which makes it sneaky. Login works fine after upgrading from v2.0.0 with no config changes; the failure surfaces only when a user signs out, as an Okta redirect-URI mismatch. Add a logout smoke test to your release checklist.
• From v1.x, or an Okta app already whitelisting authorization-code/logout: nothing to do. That's the common case if you followed Okta's own convention rather than the package's v2 default, so audit before you schedule upgrade work.
• Grep for literal URLs, not route names. route('filament-okta.{panel}.logout') still works and still initiates logout; hardcoded /authorization-code/callback/logout strings (in JS, Blade, Okta config-as-code, IaC, or docs) are what break.
• Config and route caches. php artisan config:cache in production makes path edits invisible; route:cache similarly hides paths() changes. After any change: config:clear && route:clear, then route:list --name=filament-okta to confirm the actual endpoints.
• Debug the redirect, not the code. Almost every logout problem here is a mismatch between the URI the package emits and the URI whitelisted in Okta. Log the resolved sign-out redirect URI once and diff it against the Okta app config before reading any PHP.
• Extension points are deliberately narrow: per-panel config plus paths(). If you find yourself wanting to override the controller behaviour, that's a signal to reconsider the flow rather than to patch around the package.
• Version matrix: Filament 5 × Laravel 11/12/13 × PHP 8.3/8.4. Confirm your app sits inside that before filing anything — Laravel 10 or PHP 8.2 is simply out of scope for this release.