Laravel Jetstream Passport Laravel Package

Getting Started

This package bridges Laravel Passport's OAuth authorization flow with a Jetstream (Inertia + Tailwind) front end. Passport ships bare-bones Blade views for the "authorize this client" screen; this package supplies views that match Jetstream's stack so consent screens don't look like a different application.

Minimal setup:

1. Require the package alongside Passport and Jetstream (composer require headerx/laravel-jetstream-passport).
2. Ensure Passport is installed and migrated (php artisan passport:install) and that your User model uses Laravel\Passport\HasApiTokens.
3. Publish the package's views/assets if you intend to customise them (check the service provider's publishes() calls — publish tags are the first thing to look at, since the whole value of this package is the view layer).
4. Confirm the Jetstream middleware stack is active on the routes that render the authorization screen; the authorize view typically needs session/auth middleware to resolve the requesting user and the OAuth client.

First use case: register a Passport client (php artisan passport:client), hit the /oauth/authorize flow from a third-party app, and verify the consent prompt renders in Jetstream styling with Approve/Deny actions wired to the correct POST endpoint.

Where to look first: the package's resources/views directory and its service provider — that's where the override of Passport's default oauth.authorize view is registered. v1.0.2 specifically adds an authorize view, so diff that file against Passport's stock authorize.blade.php to understand what was replaced.

Implementation Patterns

View override over forking Passport. The intended pattern is to let Passport own the routes and controllers while this package swaps the presentation layer. Don't reimplement AuthorizationController; customise the published view and leave the grant logic alone.

Publish-then-edit for branding. Publish views into resources/views/vendor/..., then adjust copy and layout to match your app's design system (Jetstream's x-jet-* components or your own). Keeping published views in version control makes Jetstream/Tailwind upgrades reviewable.

Inertia vs. Blade decision. If the shipped authorize view is a Blade view rendered inside your Jetstream layout, treat it as a full-page, non-Inertia response. If you need it as an Inertia page, wrap it in an Inertia response from a small custom controller and keep the package's markup as the page component — but be aware the OAuth POST still targets Passport's route.

Scoped consent screens. For multi-tenant or role-gated apps, gate which users can approve clients (e.g. only users with an api-access permission). The view is the natural place to surface scopes/abilities so users understand what they're granting.

Testing the flow. Feature-test the consent round trip: acting as a user, GET /oauth/authorize with valid client_id/redirect_uri/response_type, assert the view renders, then POST to approve and assert the redirect carries an authorization code. Cover the deny path too.

Upgrade cadence. With a small package like this, pinning to a caret constraint and reviewing the changelog per minor is cheap — the surface area is mostly views, so breakage tends to be cosmetic rather than architectural.

Gotchas and Tips

Publish tags matter. If you publish once and later upgrade, the published files shadow new package versions — you won't get the v1.0.2 authorize view until you republish or manually diff. Track published files deliberately.

Redirect URI strictness. Most "authorize screen is broken" reports are actually Passport rejecting an unregistered or non-exact redirect_uri before the view ever renders. Verify the client record before blaming the package.

PKCE and grant types. Confirm which grant type your client uses; the consent screen only appears in the authorization-code flow. Clients using client-credentials or password grants never hit this view, which can look like the package "isn't working."

Middleware context. The view expects the web middleware group (sessions, cookies, CSRF). If you've customised Passport's route registration or moved /oauth/authorize under an API-only stack, the approve POST will fail CSRF validation.

Tailwind purge / Jetstream version drift. Jetstream v1 vs v2 vs v3 differ in component names and CSS setup. After upgrading Jetstream, re-check that the authorize view's classes survive purging and that any x-jet-* components still exist.

Extension points. Prefer overriding the view and, if needed, binding a custom AuthorizationViewResponse (Passport's documented hook) over editing vendor files. That keeps the upgrade path to this package intact.

Debugging tip. Use php artisan route:list --path=oauth to confirm which controller and middleware are actually serving /oauth/authorize, and check view:clear after publishing — stale compiled views are a common false alarm.

Version note (v1.0.2). This release is small — an added authorize view plus README updates. No breaking changes or deprecations are signalled; treat it as a safe patch/minor bump and republish views if you want the new authorize screen.