Jwtauthroles Laravel Package

Product Decisions This Supports

• Identity provider (IdP) consolidation: Supports the decision to make FusionAuth the system of record for users and credentials while Laravel apps stay stateless. If we're evaluating "centralize auth vs. per-app password tables," this package is the cheap Laravel-side glue that makes that strategy viable without a custom build.
• Build vs. buy on the auth integration layer: The package answers a narrow but recurring question — do we write our own JWKS fetch/cache, key-rotation handling, signature verification, and role-claim mapping, or do we take a dependency? It lets us scope that build at roughly hours-to-days rather than a sprint.
• Framework-compatibility risk: Release 1.3.1 adds explicit Laravel 9 and 10 support. That materially reduces the integration risk for apps on those majors and removes a previously necessary compatibility spike. It does not signal support for Laravel 11+; those versions remain unverified unless we test or patch them ourselves.
• Roadmap: enterprise/B2B readiness: Token-based auth with roles carried in claims is a prerequisite for multi-tenant admin consoles, SSO for partner organizations, and role-gated features. Adopting it (or consciously rejecting it) informs how we sequence SSO work and whether it's a Q-now or Q-later item.
• Feature scoping for RBAC: Because roles arrive as JWT claims rather than local tables, it forces an explicit product decision: are role assignments governed in FusionAuth (ops-owned, one place to audit) or in our app database (app-owned, per-tenant flexibility)? That's a product/policy call, not just an engineering one.
• Architecture: monolith vs. services: If we intend to have multiple services accept the same token, a shared verification approach (JWKS endpoint, asymmetric keys) removes per-service session stores. This supports or rules out a service-split roadmap item.
• Risk budget for dependencies: With low adoption, zero dependents, and a thin maintenance record, adopting this is still a "we own the code if it breaks" decision. Release 1.3.1 is a compatibility update, not evidence of an active support relationship. It supports an explicit call on whether to vendor/fork it behind our own interface, or defer until a real SSO requirement lands.

When to Consider This Package

Adopt only when most of these are true:

• FusionAuth is already the committed IdP, or we are actively piloting it. The package is purpose-built for that issuer; using it with anything else means re-validating assumptions it makes about claim shape.
• The Laravel app is an API/token consumer, not the login surface. FusionAuth (or a hosted login page) handles sign-in, refresh, and consent; Laravel only needs to verify and authorize.
• Roles genuinely live in the token. If our authorization model needs per-request database lookups, dynamic permissions, or resource-level ACLs, claim-carried roles will fight us.
• We want JWKS with rotation handled, or we have a PEM public key we control and want the simpler direct-key path.
• We are on Laravel 9 or 10, which 1.3.1 explicitly supports, or we have verified/forked the package for newer Laravel majors. Do not assume Laravel 11+ compatibility from this release note.
• We're comfortable owning a small, low-maintenance dependency. That means reading ~a few hundred lines, pinning a version, and being prepared to fork. MIT license makes that permissible.
• We can still verify security behavior ourselves — issuer/audience validation, expiry/not-before handling, JWKS caching, key rotation, and role-claim mapping. The 1.3.1 release improves framework compatibility but does not remove the need for a short security review.

Look elsewhere when:

• We're not on FusionAuth. tymon/jwt-auth (self-issued tokens), laravel/passport (full OAuth2 server), or laravel/sanctum (SPA/session tokens) fit better and are actively maintained. For generic OIDC, use a maintained OIDC client rather than a single-IdP package.
• We need the full auth flow, not just verification — login, refresh, logout, password reset, MFA enrollment. This package does one thing; it is not an auth system.
• Session-based web auth is the requirement. Sanctum plus a standard guard is the lower-risk path.
• We need issuer/audience validation guarantees, token revocation, or introspection. Verify these exist in the source first; if they don't, the "cheap dependency" becomes a security review project.
• We are on Laravel 11+ and cannot fork or patch. The latest release only claims Laravel 9/10 support, so newer majors are an unverified path.
• Procurement or an SLA applies. Zero dependents means no third-party production evidence and no realistic support channel; that's a poor fit where an unsupported dependency is a compliance problem.
• Effort saved is small relative to risk. JWKS fetch-and-cache plus signature verification plus claim mapping is a well-understood 1–3 day build with tests. Release 1.3.1 lowers the framework-compatibility objection but does not change the adoption signal much; "build 200 lines we fully understand" remains a legitimately competitive option. Price the dependency against that, not against zero.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed connector that lets our Laravel applications trust logins issued by FusionAuth, so user accounts and roles live in one governed system instead of being re-implemented per app. The strategic value is consolidation and SSO readiness, not the package itself — the package is at most a few days of saved engineering. Release 1.3.1 adds Laravel 9 and 10 support, which removes one compatibility objection for current apps, but it is a maintenance update, not a sign of broad adoption or vendor support. The recommendation remains a time-boxed spike inside the SSO initiative, with a fallback to a short in-house implementation. Low cost, low commitment, and no lock-in: the license permits us to fork or replace it at will.

To engineering: It gives us a guard/middleware that verifies a FusionAuth-issued JWT — via PEM public key or the JWKS endpoint, which implies key fetch and rotation handling — and surfaces roles from claims for authorization. It does not provide login, refresh, revocation, or introspection; those stay with FusionAuth. Release 1.3.1 explicitly supports Laravel 9/10, so confirm our app is in that range; for Laravel 11+, treat compatibility as unverified and budget a patch or fork. Before adopting, still confirm: that iss/aud/exp/nbf are all validated, how JWKS responses are cached and how key rotation is handled, and how role claims are named and mapped. Assume we own it: pin the version, wrap it behind our own auth abstraction so it can be swapped, and add tests around expired, malformed, wrong-issuer, and rotated-key tokens. Benchmark the alternative honestly — the same behavior is roughly 200–300 lines plus tests using a maintained JWT library — and treat the package as a shortcut we may fork rather than as a vendor relationship.