Laravel Mautic Laravel Package

Technical Evaluation

Architecture fit

• The package remains a conventional Laravel integration layer for Mautic: configuration-driven connections, Artisan commands (mautic:diagnose, mautic:oauth:callback-url), and token persistence. v1.1.0 does not introduce migrations or token-storage changes, so it preserves the existing persistence model and APP_KEY dependency.
• The new browser OAuth capability is opt-in and disabled by default. Package-owned authorization and callback routes are only registered when explicitly configured, and authorization is delegated to a host-provided OAuthBrowserAuthorizer that denies by default. This keeps the package out of the host application’s authentication and authorization boundary, which is the correct architectural posture for a TPM to endorse.
• Runtime credential resolution now supports Laravel’s environment repository for client secrets while retaining process-environment and custom provider compatibility. This improves fit with Laravel’s configuration and secret-management conventions but introduces a distinction between cached configuration and runtime environment values that must be understood operationally.
• The fixes are directionally security-positive: result redirects no longer rebuild a destination from the request Host header, and callbacks from superseded authorization attempts preserve the active session context. Both reduce exposure to host-header manipulation and multi-tab/retry flow breakage.

Integration feasibility

• Integration effort is moderate and mostly configuration-led for existing consumers. Host-owned OAuth routes remain supported, so current integrations are not forced to migrate. Adopting package routes requires three explicit actions: enable the OAuth routes, bind a host authorizer, and configure connection allowlisting plus route settings.
• Published-config applications must manually merge the new oauth.routes block into config/mautic.php. This is a routine but error-prone step; teams that habitually run vendor:publish --force risk overwriting host configuration.
• Cached-configuration deployments must supply the client secret through the process environment visible to PHP-FPM, CLI, the scheduler, and queue workers. That is feasible in most Laravel estates but requires coordination across deployment surfaces, not just the web runtime.
• No database migration or token-record transformation is required, which materially lowers rollback risk and shortens the change window.

Technical risk

• Medium: OAuth browser flows are security-sensitive and now partially package-owned when enabled. The deny-by-default authorizer and connection allowlisting are strong mitigants, but misconfiguration (over-broad allowlists, an authorizer that permits too much, or a permissive result route) is a realistic failure mode.
• Medium: Canonical callback URL resolution depends on a trusted app.url, with per-connection redirect_uri taking precedence. Behind load balancers, reverse proxies, or multi-domain deployments, an incorrect app.url or missing trusted-proxy configuration will produce callback mismatches that are difficult to diagnose from application logs alone.
• Medium: Credential resolution across four runtime contexts (FPM, CLI, scheduler, queue workers) is a recurring source of "works in the web request, fails in the worker" incidents. The release notes explicitly require restarting long-running workers after configuration or environment changes.
• Low–Medium: Validation coverage is strong at the unit/integration level (334 tests, all PHP 8.4/8.5 × Laravel 12/13 combinations, Pint, Larastan level 8) but the release explicitly states that live Mautic and opt-in MariaDB acceptance tests were not rerun. For a release touching OAuth behavior, that is a meaningful assurance gap and should be closed before broad production rollout.
• Low: The relative Location header change and session-context preservation are behavioral fixes; hosts with custom middleware that rewrites redirects should confirm no regression.

Key questions

• Which Mautic versions and OAuth grant types are considered supported and tested for the package-owned browser flow?
• What is the expected behavior when a connection is removed from the allowlist while a user has an in-flight authorization attempt?
• Does the host authorizer receive enough context (user, connection, intended scopes, return destination) to make a sound policy decision, and is that contract documented?
• How are token refresh failures surfaced to operators — through mautic:diagnose only, or through events/log channels suitable for alerting?
• Is there guidance for multi-node deployments regarding session storage, OAuth state, and concurrent refresh by queue workers?
• What is the maintainers’ plan and timeline for rerunning live Mautic and MariaDB acceptance tests against v1.1.0?
• Are oauth.routes settings safe to leave disabled in production while enabling them only in non-production environments for validation?

Integration Approach

Stack fit

• Compatible with PHP 8.4/8.5 and Laravel 12/13, matching a modern Laravel baseline. Teams on older PHP or Laravel versions are out of scope for this release and must not assume support.
• Fits Laravel idioms: config publishing, environment repository for secrets, Artisan diagnostics, route-level configuration for prefix/middleware/names, and a host-bound authorization contract.
• The read-only mautic:oauth:callback-url command is a genuine integration aid — it lets platform and network teams agree on the exact redirect URI before registering the Mautic client, reducing a common class of setup failures.
• Sanitized credential availability reporting in mautic:diagnose supports pre-flight checks without leaking secrets, which fits change-management and audit requirements.

Migration path

• From 1.0.0: no migrations, no token-storage changes, no APP_KEY rotation. Existing host-owned OAuth routes continue to work unchanged; this is effectively an additive release for those consumers.
• For hosts adopting package routes: merge oauth.routes into config/mautic.php by hand, bind OAuthBrowserAuthorizer, configure the connection allowlist, then enable routes. Do not use vendor:publish --force.
• Follow docs/oauth-host-adoption.md before removing superseded host OAuth infrastructure. Removal should be a separate, later change once the package-owned flow has been validated in production traffic.
• Rollback is low-cost: disable package routes, restore host-owned routes, and retain existing token records. Preserve environment variables and APP_KEY throughout.

Compatibility

• Configuration compatibility is the main hazard: cached configuration will not observe new environment values, so secret injection must happen where the process environment is read at boot.
• Reverse-proxy and multi-domain deployments must set app.url deliberately and configure trusted proxies; per-connection redirect_uri overrides should be used where a single canonical URL cannot represent all entry points.
• Queue workers, scheduler tasks, and CLI commands must share the same credential environment as web requests; divergence is the most likely source of partial outages.
• Session driver choice matters for the browser flow, particularly the preserved-session behavior for replaced authorization attempts; shared session storage is advisable for multi-node deployments.

Sequencing

1. Upgrade the package in a non-production environment; merge oauth.routes configuration manually and confirm config caching behavior.
2. Run mautic:diagnose and mautic:oauth:callback-url to validate credential resolution and the canonical redirect URI for each connection.
3. Enable package OAuth routes in a staging environment with a restrictive allowlist and a host authorizer that permits only test identities.
4. Exercise success, denial, cancellation, replaced-attempt, and multi-tab flows; specifically test behind the production proxy topology.
5. Validate queue worker and scheduler credential access, then restart long-running workers as part of the deployment runbook.
6. Ramp to a small production cohort while keeping host-owned routes available; only then decommission superseded host infrastructure per the adoption guide.
7. Close the assurance gap by arranging live Mautic acceptance testing (owned internally or confirmed with maintainers) before full rollout.

Operational Impact

Maintenance

• Low ongoing maintenance for existing consumers: additive configuration, no schema changes, no token migration. The principal maintenance task is keeping config/mautic.php in sync with upstream oauth.routes defaults through manual merges rather than force-publishing.
• Teams enabling package routes take on ownership of the OAuthBrowserAuthorizer binding and the connection allowlist. These are small but security-critical artifacts that need code review and change control.
• Documentation now covers OAuth setup and host adoption end to end, which reduces the internal knowledge burden but should still be adapted into the team’s own runbook.

Support

• Diagnosability improves: sanitized credential reporting and the callback-URL command give first-line support concrete checks before escalation.
• Expected support themes will be redirect-URI mismatch, allowlist denials, cached-configuration staleness, and worker credential drift. Each should have a documented triage step.
• The unrerun live Mautic acceptance tests mean early production issues may not be reproducible in CI; support should capture request/response metadata and Mautic-side logs during the initial rollout window.

Scaling

• The browser OAuth flow is session-bound; horizontal scaling requires shared session storage and consistent app.url/redirect_uri resolution across nodes.
• Token refresh concurrency across multiple queue workers is a latent scaling concern. Where refresh tokens rotate, parallel workers on the same connection can contend; operators should know whether the package serializes refresh or relies on retry behavior.
• Credential resolution at runtime scales acceptably, but secret distribution to every runtime surface (FPM pools, CLI hosts, scheduler, workers) grows in complexity with fleet size. Centralized secret injection via the environment repository is preferable to per-host files.

Failure modes

• Deny-by-default authorizer unbound or misbound: package routes enabled without a host authorization binding will deny access. Correct by design, but will present as an outage if enabled prematurely.
• Allowlist omission: a legitimate connection not listed will fail authorization with little end-user explanation; requires clear error messaging and documented remedy.
• Redirect-URI mismatch: incorrect app.url, missing trusted-proxy configuration, or a per-connection override conflict will break callbacks, typically only in production topology.
• Stale cached configuration: config:cache combined with secrets supplied only at request time will yield missing or empty client secrets; the documented mitigation is process-environment injection plus worker restarts.
• Worker drift: queue workers and scheduler running with an old environment will fail token operations while web requests succeed, producing intermittent, hard-to-attribute errors.
• Interrupted or replaced authorization attempts: session-context preservation reduces breakage, but users abandoning flows mid-callback can still leave partial state; support should treat these as expected, recoverable events.
• Host-header-derived redirect regression (pre-1.1.0): resolved by this release; consumers who pinned 1.0.0 should prioritize upgrading, as the prior behavior is a plausible open-redirect vector.

Ramp-up

• Estimated effort: roughly 2–4 engineer-days for a team adopting package-owned OAuth routes in a single-connection deployment (configuration merge, authorizer binding, staging validation, runbook updates), plus additional time proportional to the number of connections, proxy topologies, and runtime surfaces.
• Teams staying on host-owned routes should budget under a day: upgrade, merge configuration, run diagnostics, confirm no behavioral change.
• Prerequisites before starting: known canonical app.url per environment, trusted-proxy configuration confirmed, shared session store decision made, and secret injection path agreed for FPM, CLI, scheduler, and workers.
• Recommended gate: do not remove host-owned OAuth infrastructure until at least one full production authorization, refresh, and revocation cycle has completed successfully on the package-owned path, and until live Mautic acceptance coverage for v1.1.0 has been confirmed.