Simple Oauth2 Client Laravel Package

Product Decisions This Supports

• Login funnel conversion and deep-link retention. preserve_intended_url (default true) means a user who follows a shared link to a gated page is returned there after authenticating instead of being dumped on a generic success route. This is a measurable funnel decision, not a cosmetic one: it affects activation on invite links, shared documents, checkout deep links, and email campaign landing pages. PMs can now treat "authenticate mid-journey" as a supported path rather than a leak, and should instrument it (drop-off before vs. after login, post-login destination distribution) before assuming the default is right for every surface.
• Route surface as a product/branding decision. route_prefix (default oauth) lets the callback live at /auth/callback or any brand-aligned path. Useful when the default path collides with an existing route, when multiple auth flows must coexist under distinct prefixes, or when a customer-facing URL is part of the product story. Route names are unchanged (oauth.request, oauth.callback), so this is a low-risk presentation change without a code-wide refactor — a cheap way to satisfy a design or platform review.
• Reduced "login is broken" support load. The redirect-URI fix derives the advertised URI from APP_URL plus the actual route path, so the value announced to the provider cannot drift from the route that serves the callback. Previously, publishing config without running oauth:install advertised the bare domain, and any non-default callback path produced a 404 after the user had already authenticated — the worst failure mode, since the user has spent effort and is then dropped. For a PM this is a defect class worth closing before scaling any acquisition spend into an OAuth-gated funnel.
• Build vs. buy tilts further toward buy. The package now owns a subtle, security-relevant detail — rooting the redirect URI in APP_URL rather than the incoming request — which is exactly the kind of thing an in-house implementation gets wrong behind a TLS-terminating reverse proxy or with a spoofable Host header. That is engineering time and incident risk a team does not need to re-derive.
• Roadmap sequencing. This is a low-ceremony release: one new feature with a safe default, one configuration addition, one correctness fix, and a deprecation that only affects a narrow custom-routing setup. It can ride along with any in-flight auth work rather than claiming its own slot.

When to Consider This Package

Adopt when:

• Your Laravel application delegates authentication to an external OAuth/OIDC provider and you want the callback, redirect-URI derivation, and post-login destination handled consistently rather than hand-rolled.
• You have gated content reached by deep links (invites, shared resources, email CTAs) and want the pre-login destination preserved by default.
• You are behind a reverse proxy or load balancer terminating TLS, or otherwise cannot trust Host/scheme from the request — the APP_URL-rooted redirect URI is a genuine correctness advantage here.
• You want the callback on a branded or non-default path; route_prefix makes this a config change plus one provider registration, not a fork.
• You are already on the package: upgrading is cheap and removes a latent 404-after-authentication failure.

Look elsewhere or pause when:

• You declared your own routes against OAuthController to serve the callback at a custom path. This is the one setup requiring action: OAUTH_CALLBACK_URI is no longer read, and the advertised URI now follows the package route. Either set OAUTH_ROUTE_PREFIX to that same prefix or register the new URI with your provider. Budget the provider-side change and a comms note; get this wrong and every login fails immediately after deploy.
• You run a multi-tenant setup where APP_URL is not a single stable value per deployment. The fix intentionally ignores the incoming request, so per-tenant hostnames need to be resolved at config/runtime level, not by relying on request introspection.
• You need a full authorization server (issuing tokens to third parties), fine-grained scopes/consent management, or social login with many providers — this is a client-side integration, not an identity platform.
• You are mid-freeze on auth. The deprecation is silent (the key remains in config but has no effect), which is convenient for upgrades but means a stale config can look correct while doing nothing. Verify rather than assume.

How to Pitch It (Stakeholders)

For executives: This release removes the most expensive kind of login failure — the one that happens after the user has already authenticated — and keeps users on the path they came for. Two things matter commercially. First, deep links now survive login by default, so acquisition spend on shared links, invites, and email campaigns is no longer partially wasted at the sign-in wall. Second, the redirect URI is now derived from a single source of truth (APP_URL plus the real route), which eliminates a configuration class that failed silently on the provider's side and generated support tickets we could not reproduce locally. Cost to adopt is near zero: a dependency bump, an optional config change if we want a branded callback path, and one provider dashboard update only if we are in the small group with custom callback routes.

For engineering: The security-relevant change is that the redirect URI is rooted in APP_URL and never in the incoming request. That closes three real failure modes at once: http:// advertised behind a TLS-terminating proxy (since TrustProxies is not enabled by default in Laravel 11+), a spoofable Host header, and APP_URL being ignored on a local server — each producing an unregistered URI and a hard login failure. Advertised URI and served route can no longer disagree, so publishing config without running oauth:install no longer advertises the bare domain.

Migration asks: One audit item, not a refactor. OAUTH_CALLBACK_URI (config key oauth.callback) is no longer read. The key is retained so published configs keep loading, but it has no effect — so a stale value will not error, it will just be ignored. Set OAUTH_ROUTE_PREFIX if we need a custom path. The only setup requiring action is one that registered its own routes against OAuthController and matched OAUTH_CALLBACK_URI to it: align the prefix or register the new URI with the provider before deploying. oauth:install now prompts for the prefix and prints the exact redirect URI to register, which should be our go-to for verification rather than reading config by hand. Route names are unchanged, so existing route() calls keep working.