Filament Passport Laravel Package

Technical Evaluation

Architecture fit

• The plugin is a thin Filament UI layer over Passport's existing Eloquent models (OauthClient, OauthAccessToken, OauthAuthCode). It adds no tables, no parallel identity store, and no proprietary persistence. From a TPM standpoint that makes adoption reversible and low-blast-radius: removing the package removes a UI, not data or auth behavior.
• It bundles two capabilities that should be evaluated — and if necessary adopted — separately:
  1. Admin resources for clients, tokens, and authorization codes (ops/admin value, internal audience).
  2. Consent Blade views for authorization, device authorization, and device user code (user-facing value, sits inside the OAuth redirect flow).
• The consent views are the higher-leverage half. Passport does not ship them; every team hand-builds them. That is where the estimated sprint of saved work actually lives. They are also the higher-risk half, because a defect there is user-facing and security-adjacent rather than cosmetic.
• Assumes the conventional shape: Filament panel as back office, Passport as the API auth layer, one default guard. Multi-panel and multi-tenant behavior are unverified and must not be assumed on the roadmap.

Integration feasibility

• Very low ceremony: composer require, one ->plugins([FilamentPassportPlugin::make()]) line in the panel provider, optional config and view publishing. No package-owned migrations.
• Hard prerequisite: Passport must already be installed, keyed, and migrated (php artisan install:api --passport). If Passport is not already in the architecture, this package is inert — it is not a reason to adopt Passport.
• Access control is built in and ordered: viewFilamentPassport gate → canAccess() callback → open access by default. The default-open behavior is the single most important planning detail: it means "install it and it works" is also "install it and it is unprotected." That must be an explicit acceptance criterion, not an afterthought.

Technical risk

• Maturity / bus factor. 1 star, 0 dependents, single maintainer, first tagged release v1.0.0. There is no adoption signal, no vendor SLA, and no observable BC policy. Justification must come from reading the source, not from the ecosystem. MIT licensing makes a fork a practical contingency — budget for it rather than assume it away.
• Security-relevant surface, two ways. Token and client administration is a privilege-escalation surface: anyone with panel access can potentially enumerate and revoke credentials. Consent screens render user-facing HTML inside the OAuth redirect flow, which is a phishing / XSS / redirect-validation class of risk. Both warrant a security review as a scheduled line item, not functional UAT alone.
• Support-matrix breadth. Filament 4.x and 5.x, Passport 12.x and 13.x, with device flow gated on Passport 13. Cross-version support is a positive maintenance signal but multiplies our own test permutations.
• Unknowns that gate commitment. Composer constraints for laravel/framework, filament/filament, and laravel/passport are not in the README; policies, test coverage, and CI status are not documented.

Key questions

• What are the exact version constraints in composer.json, and do they permit our pinned Laravel/Filament/Passport versions?
• Does the package ship policies or gates for its resources, or does it inherit Filament's default panel access? Who is authorized to see tokens by default?
• Can the consent views be enabled independently of the admin resources — i.e., can we take the views without exposing token CRUD (or vice versa)? The config suggests yes for views; confirm for resources.
• Do the consent views preserve Passport's state, PKCE, and redirect-URI validation semantics exactly, and are outputs Blade-escaped?
• Does "revoke" in the UI map to Passport's real revocation semantics (refresh tokens, related tokens) or only to row deletion? This determines whether it is safe as an incident-response tool.
• What is the test coverage and CI status, and are there any consumers beyond the maintainer's own projects?
• Who owns the upgrade path across Filament and Passport majors — upstream, or us via fork?

Integration Approach

Stack fit

• Hard gate, not a preference: Laravel + Filament 4.x/5.x + PHP 8.2+ + Passport 12.x/13.x. A panel still on Filament 3 disqualifies it outright.
• Device Authorization grant requires Passport 13. Treat that as a product decision about Passport upgrade timing, and do not let a UI plugin drive an auth-layer upgrade.

Migration path

• Purely additive. There is no data migration and no cutover window.
• The only "migration" is retiring in-house consent views or hand-rolled Passport CRUD in favor of the published versions. If we currently have no consent UI, this is greenfield wiring — cheaper, but with no incumbent behavior to diff against for regressions, which raises the value of pre-merge security review.
• Where an in-house consent screen exists, sequence the swap behind the plugin's views config so rollback is a config toggle, not a deploy.

Compatibility

• Validate the full matrix on a throwaway branch before any commitment: install, boot the panel, exercise authorization code, PKCE, client credentials, and — only if on Passport 13 — device flow.
• Confirm the panel's auth guard, tenancy configuration, and theme do not collide with resource registration. Multi-panel applications must test each panel independently, including panels that should not show the resources.

Sequencing

1. Spike branch. Read composer.json; composer require; boot a panel; confirm the three resources render. Cheap go/no-go.
2. Security read of the consent Blade views against what Passport's authorization controller expects. This happens before staging, not after.
3. Gate the resources behind a gate or policy. Do not ship on default open access.
4. Publish config and views into the repo and code-review them, consciously accepting upstream drift as the tradeoff. Keep overrides thin so a fork stays cheap.
5. End-to-end UAT of each flow we intend to support against a real registered client, including a token revocation exercise.
6. Pilot on an internal or low-blast-radius panel, then formalize as a shared dependency only after consent flow and revocation are verified in our environment.
7. Pin the exact version and record the fork contingency in the ADR.

Operational Impact

Maintenance

• Ownership must be named. No vendor support exists, so maintenance is necessarily internal. Assign a code owner for the pinned version, the published config, and the published views.
• Upgrades are driven by our Filament and Passport major bumps, not by the package's cadence. Both are breaking-change-dense, and the cross-version support matrix means the package may lag. Plan upgrades as paired work: bump Filament/Passport, then re-verify or replace the plugin.
• Published views are a fork in miniature: once copied into resources/views/vendor/, upstream fixes don't reach us. Keep the diff from stock small and logged.

Support

• There is no escalation path. The internal SME who performed the security read is the de facto support owner, and that needs to be a staffed role, not an assumption.
• Build a short runbook: who can access the plugin's resources, how to revoke a compromised client, and what the consent screens say and why. This turns incident response from an engineering ticket into a documented UI action — the primary operational payoff.
• Support load is low in steady state and spiky at framework upgrade time. Plan capacity accordingly rather than as a flat line.

Scaling

• This is an admin-surface concern, not an API-throughput concern. It does not sit on the request path for token issuance other than the consent views.
• Two things to watch as the install grows: (a) rendering and searching large oauth_access_tokens and oauth_auth_codes tables in a panel — confirm pagination and query behavior against realistic volumes; (b) whether revocation is per-record only. If bulk revocation ("kill all tokens for this client now") isn't supported, incident response at scale degrades back to SQL, which erodes the package's main value proposition. Verify early.
• Consent views inherit the app's rendering path; their load profile is normal Blade, but confirm caching and asset assumptions match our deployment.

Failure modes

• Consent view defect or drift → users cannot complete authorization; third-party integrations break in a user-visible way. Highest-severity failure mode, and the one most likely to arrive via an upstream change or a stale published view.
• Misconfigured access control → token and client enumeration by anyone reaching the panel. Low-probability, high-impact; mitigated by gating at install time.
• Upstream major bump → panel boot failure on deploy, or silent resource regression. Mitigated by pinning and a staging verification step.
• Maintainer abandonment → no upstream fixes. Mitigated by MIT fork readiness; the cost is a maintained fork, so the exit trigger should be defined up front (e.g., no release in N months, or an unpatched security-relevant issue).
• Revocation semantics mismatch → operators believe a credential is dead when a related refresh token is live. Validate the behavior once, in writing.

Ramp-up

• Engineering ramp is minimal for anyone already fluent in Filament: an afternoon to register, publish, and read the source. The spike is days, not weeks.
• The real ramp is OAuth domain knowledge for whoever customizes the consent views — scopes, PKCE, redirect validation, device flow UX. That is a domain-skills dependency, not a package-skills one, and should be staffed accordingly.
• Stakeholder framing: zero license cost, roughly a sprint of custom UI avoided, risk concentrated in maturity and security review rather than money or integration effort. The correct commitment is a scoped pilot with defined exit criteria, not a platform-wide rollout — and a documented decision that we own this surface if the maintainer does not.