Simple Oauth2 Client Laravel Package

Technical Evaluation

Architecture fit. The package remains a conventional Laravel OAuth client package: a service provider, publishable config/oauth.php, package routes named oauth.request / oauth.callback, an OAuthController, and an oauth:install artisan command. 3.2.0 does not change that shape. It tightens the coupling between the advertised redirect_uri and the actual package route by deriving the URI from APP_URL plus the resolved callback route path, instead of concatenating APP_URL with an independently configured OAUTH_CALLBACK_URI. That is the correct architectural direction: one source of truth for the callback path.

The new route_prefix (OAUTH_ROUTE_PREFIX, default oauth) decouples the path from the route name, which is a clean way to move the callback without breaking route('oauth.callback') call sites. The new preserve_intended_url (default true) reuses Laravel's intended-URL behaviour, which is idiomatic for the framework.

Integration feasibility. Low for a standard Laravel app: bump the dependency, optionally re-run oauth:install, confirm the printed redirect URI against the provider, and verify route:list. Moderate only for applications that declared custom routes against OAuthController and set OAUTH_CALLBACK_URI to match — those now have a silent behaviour change and must either set OAUTH_ROUTE_PREFIX to the same prefix or register the newly advertised URI with the provider.

Technical risk. Low-to-medium, concentrated in three areas:

• Silent deprecation. OAUTH_CALLBACK_URI remains in the config file but is no longer read. Teams that assumed it still controls the advertised URI will get a provider-side redirect_uri mismatch or a post-authentication 404 with no configuration error at boot.
• Deploy-window mismatch. If OAUTH_ROUTE_PREFIX changes before the provider has the new URI registered (or vice versa), users authenticate successfully and then fail at callback. This is a user-visible failure after credential entry, not an early failure.
• APP_URL dependency. Deriving from APP_URL fixes request-derived URI problems (proxy TLS termination, spoofed Host, local server host), but it hard-codes a single canonical origin. Multi-domain, multi-tenant, or per-tenant provider apps may not fit a single global prefix and APP_URL.

preserve_intended_url defaulting to true is a behaviour change for existing installs: users who previously always landed on the configured success route will now return to a stored deep link. That is usually desirable, but it should be reviewed for redirect-validation assumptions and for any post-login UX that assumes a fixed landing page.

Key questions.

• What are the supported Laravel and PHP version ranges for 3.2.0, and is route_prefix compatible with route:cache?
• Can route_prefix contain nested segments (e.g. auth/sso), and is it validated?
• Is there a supported per-request or per-tenant override of the redirect URI, or is APP_URL + prefix strictly global?
• Does preserve_intended_url rely on Laravel's session url.intended with same-host validation, or does it accept arbitrary stored URLs?
• Does the package emit a deprecation warning when OAUTH_CALLBACK_URI is still present, or is it fully silent?
• Are the route names oauth.request / oauth.callback covered by a stability guarantee across the 3.x line?

Integration Approach

Stack fit. Standard Laravel package install: Composer require, service provider auto-discovery, optional vendor:publish of config/oauth.php, and php artisan oauth:install. The release explicitly targets modern Laravel (the notes reference Laravel 11+ TrustProxies defaults), so it should slot into a current Laravel application without custom bootstrapping. Applications using Laravel's route cache and standard APP_URL configuration should fit without adaptation.

Migration path. Three cohorts:

1. Default installs (no custom callback route, no meaningful OAUTH_CALLBACK_URI). Upgrade is effectively transparent. The advertised URI becomes APP_URL + /oauth/callback, which matches what most providers already have registered. Verify with route:list and the URI printed by oauth:install; remove OAUTH_CALLBACK_URI from .env as cleanup.
2. Installations that moved the callback via OAUTH_CALLBACK_URI. Set OAUTH_ROUTE_PREFIX to the same path segment before or with the upgrade, keeping OAUTH_CALLBACK_URI in place during the transition (it is inert but harmless). Confirm the advertised URI is unchanged, then delete the old key.
3. Applications with custom routes against OAuthController. Highest effort. Decide whether to keep the custom route (set OAUTH_ROUTE_PREFIX to match it) or adopt the package route (register the new URI with the provider). Do not deploy without one of these two actions.

Compatibility. Route names are stable, so route('oauth.callback') call sites and any redirects built from route names keep working. Published config files keep working because the deprecated key remains present. The compatibility break is behavioural, not syntactic: the value of OAUTH_CALLBACK_URI no longer influences the advertised URI. Hard-coded /oauth/callback strings in provider dashboards, WAF rules, proxy rules, documentation, and end-to-end tests must be updated if the prefix changes. preserve_intended_url changes post-login destination for existing users by default.

Sequencing.

1. Pin the current version; inventory all uses of OAUTH_CALLBACK_URI, hard-coded callback paths, custom OAuthController routes, and provider-registered redirect URIs.
2. In staging, set OAUTH_ROUTE_PREFIX (and keep OAUTH_CALLBACK_URI if needed) so the advertised URI is identical before and after upgrade.
3. Deploy the package upgrade; run oauth:install or manually confirm the printed redirect URI; verify route:list shows oauth.request / oauth.callback at the expected paths.
4. Exercise the full flow: cold login, deep-link login with preserve_intended_url, login behind the TLS-terminating proxy, and login with a wrong APP_URL to confirm failure is loud and early.
5. Register or update the provider redirect URI only after the new advertised URI is verified in staging.
6. Remove OAUTH_CALLBACK_URI and any custom callback routes once the provider and application agree.
7. Update runbooks, provider configuration docs, and smoke tests.

Operational Impact

Maintenance. Ongoing maintenance is low: no new infrastructure, no new runtime dependency, no queue or storage changes. The recurring cost is configuration hygiene — a deprecated key that remains in published configs and no longer does anything. Teams should add a deployment check that flags OAUTH_CALLBACK_URI in .env and asserts that the provider-registered URI equals APP_URL + callback route path.

Support. The main support burden is diagnosability. The old failure mode (OAUTH_CALLBACK_URI decoupled from the route) produced a bare-domain or 404 redirect URI; the new failure mode is a correctly derived but unregistered URI after a prefix change. Both surface to users as a failed login after authentication. Support runbooks should start with: check APP_URL, check OAUTH_ROUTE_PREFIX, check route:list, compare against the provider dashboard. The silence of the deprecated key is a documentation and onboarding risk more than a runtime one.

Scaling. No scaling impact. The package is stateless and the redirect URI is deterministic. The one scaling constraint is architectural: route_prefix and APP_URL are global, so a single deployment advertises a single callback origin. Multi-tenant or multi-domain applications that front multiple hosts from one codebase will need separate deployments, per-tenant provider apps, or an extension point that this release does not appear to add.

Failure modes.

• APP_URL misconfigured (scheme, host, subdomain, trailing slash) → provider rejects the redirect URI before authentication.
• APP_URL set to http:// behind a TLS-terminating proxy → mismatch with the provider's https:// registration. The release correctly avoids request-derived URIs, but it does not fix a wrong APP_URL.
• OAUTH_ROUTE_PREFIX changed without updating the provider → 404 after successful authentication.
• Provider URI updated before application deployment → same post-authentication failure in the opposite direction.
• OAUTH_CALLBACK_URI still set and assumed authoritative → silent mismatch, no boot-time error.
• preserve_intended_url enabled with an unvalidated stored URL → potential open-redirect behaviour if the intended URL is not same-origin constrained.
• Stale route cache after a prefix change → old paths continue to be served until route:cache is regenerated.
• Spoofed Host and proxy-header issues are materially reduced by rooting the URI in APP_URL, which is a genuine operational improvement over request-derived behaviour.

Ramp-up. A developer on a standard Laravel app can adopt this in under an hour: upgrade, confirm the printed redirect URI, test one login and one deep-link login. A team with custom callback routes, multiple hostnames, or a manually managed provider configuration should budget half a day to a day for inventory, staging verification, provider coordination, and runbook updates. The release is a net simplification — fewer moving parts, one source of truth for the callback path — but the deprecation should be treated as a coordinated config migration, not a routine patch bump.