Filament Oidc Laravel Package

Product Decisions This Supports

• Enterprise SSO readiness for admin surfaces. OIDC login is a recurring procurement and security-review checkbox (Okta, Entra ID, Auth0, Keycloak, Google Workspace). This plugin is the Filament-side integration that turns that requirement into a configuration task rather than a build project.
• Build vs buy. Building OIDC plumbing (discovery, token/claim validation, identity-to-user linking, persistence) is well-understood but unforgiving work. Adopting this package trades engineering weeks for a dependency — a defensible trade for admin-panel auth, which is rarely a differentiator.
• Roadmap: identity architecture. Release 3.1.0 is an architectural signal, not just a patch: identity persistence has been extracted into jeffersongoncalves/laravel-oidc (v1.3.0), leaving filament-oidc as the Filament adapter layer. That means (a) we now take two packages instead of one, (b) the identity model is reusable outside Filament — potentially for API or other entry-point auth — and (c) the vendor is actively modularizing in single-purpose PRs, so expect further churn before the layering settles.
• Persisted identities as a product capability. Keeping OIDC identity records linked to users supports multi-provider logins per user, audit trails of which IdP an account came from, and staged migrations between identity providers.

When to Consider This Package

Adopt when:

• You run Filament admin panels and need standards-compliant OIDC sign-in.
• Your IdP speaks OIDC (not SAML-only) and you want identity records persisted and linkable to application users.
• You are willing to own a small, actively-refactoring dependency and can pin versions deliberately.

Look elsewhere when:

• You need SAML or SCIM provisioning — neither is in scope here.
• You need a mature, semver-disciplined dependency. 3.1.0 ships breaking renames in a minor version (see below). Teams with strict upgrade policies should treat the 3.x line as fast-moving and budget migration work per release.
• Your auth surface is small enough that a single Socialite provider covers it; the added indirection of a plugin plus a companion core package isn't worth it.
• Bus-factor risk is disqualifying: this is a single-maintainer ecosystem, now split across two repositories that must stay version-aligned.

What the 3.1.0 breaking change actually costs:

• Class renames (full namespaces): JeffersonGoncalves\Filament\Oidc\Models\OidcIdentity → JeffersonGoncalves\LaravelOidc\Models\OidcIdentity, and JeffersonGoncalves\Filament\Oidc\Concerns\HasOidcIdentities → JeffersonGoncalves\LaravelOidc\Concerns\HasOidcIdentities. This reaches beyond vendor code into any application models, policies, factories, seeders, and tests that reference these directly — grep for the full JeffersonGoncalves\Filament\Oidc prefix, not just the short class names.
• Config key rename: filament-oidc.identities_table → oidc.identities_table. Any config reads, env-driven overrides, or config-cache assumptions must move.
• Migration publish tag rename: filament-oidc-migrations → oidc-migrations. This is the silent-failure risk — deploy scripts or CI steps still publishing the old tag will do nothing and succeed.
• New hard dependency: laravel-oidc ^1.3.0 must be reviewed and pinned alongside.
• Mitigating factor: table name and schema are unchanged, and previously published migrations keep working. The risk is code and pipeline breakage, not data migration — which makes the upgrade mechanical and testable.

How to Pitch It (Stakeholders)

To executives: Enterprise buyers and internal security increasingly require single sign-on for admin tooling. Rather than building OIDC authentication ourselves — weeks of engineering plus permanent security-maintenance overhead — we adopt a small package that plugs OIDC into our existing Filament admin panels and records which identity provider each account came from. The trade-off is dependency maintenance: the maintainer is mid-refactor, so we pin versions and treat upgrades as scheduled work rather than automatic.

To engineering: 3.1.0 (published 2026-10-07) is a deliberate layering refactor — identity persistence moves to the laravel-oidc core, leaving this package as the Filament adapter. Good separation and a reusable identity model. The cost is a breaking rename set delivered in a minor version: two fully-qualified class namespaces, one config key, one migration publish tag, plus a new required dependency. Migration is mechanical and there are no database changes — existing tables and published migrations continue to work. Gate the upgrade on: a global search for the old JeffersonGoncalves\Filament\Oidc namespaces, updating the deploy/CI publish step to the new tag (highest silent-failure risk), pinning both packages, and a smoke test that asserts an OIDC login completes end-to-end in staging. Secondary evaluation: whether laravel-oidc's core can serve non-Filament entry points, which would improve the return on adopting the split at all.