Oauth2 Server Laravel Package

Technical Evaluation

Architecture fit. The framing as a "Laravel package" is the first thing a TPM must correct. oroinc/oauth2-server is a framework-agnostic OAuth 2.0 authorization/resource server library, forked from the bshaffer/oauth2-server-php lineage and repackaged inside the OroPlatform (Symfony/Doctrine) ecosystem. It ships storage interfaces, grant-type classes, and an Oro bundle integration layer — not Laravel service providers, facades, publishable config, or Eloquent models. In a Laravel application it can only sit behind controllers and middleware the team writes. It is the raw primitive that Laravel Passport already wraps, so adopting it means re-implementing most of what Passport delivers for free.

Integration feasibility. Technically doable, but the effort is understated by a simple composer require. The team would implement the full storage surface (client, access token, refresh token, auth code, scope) against Eloquent or a cache, adapt Illuminate\Http\Request into the library's request/response objects (historically non-PSR-7), wire grant controllers into routes, and hand-roll scope-enforcement middleware, revocation, and key management. The request/response abstraction mismatch is the single largest integration tax and the most common source of subtle, hard-to-reproduce bugs.

Technical risk. High, concentrated in four areas:

• Abandonment. 2 stars, 0 dependents, ~0.41 overall score, no external bug reporters or contributor pool. No downstream canary population exists, so any CVE, PHP 8.x deprecation, or spec gap lands on your team.
• Security surface. OAuth2 is security-critical. Redirect-URI validation, token entropy, PKCE, refresh-token rotation/replay detection, and signing-key management are precisely where a stale fork quietly diverges from current guidance (RFC 7636, 8252, 9700).
• Spec staleness. Expect authorization-code and client-credentials flows to work; assume PKCE, OIDC, token introspection, and modern rotation semantics need verification or backporting.
• Fork divergence. The Oro fork likely carries CRM-specific patches. Adopters inherit whatever assumptions those encode.

Key questions.

1. What did Oro change relative to upstream bshaffer/oauth2-server-php, and do those changes matter outside OroPlatform?
2. What are the composer.json constraints for php, illuminate/*, and psr/*? (Expect none — you pin them.)
3. Is this an actively patched fork or a frozen mirror? What is the CVE/disclosure process?
4. Which flows must we support — auth code + PKCE only, or password/implicit/client-credentials too?
5. Is OIDC or token introspection in scope now or plausibly within 12 months? If yes, disqualify this package.
6. Does adopting this accelerate or block our partner-API / enterprise-readiness roadmap timeline?

Integration Approach

Stack fit. Poor-to-moderate as a first choice; acceptable only as a deliberate lower-level substitute. laravel/passport (built on league/oauth2-server) delivers migrations, guards, middleware, artisan commands, PKCE, and actively maintained upstream — the correct default for Laravel. Choose this package only for a specific reason: an existing bshaffer-lineage deployment, a hard constraint against League, or OroPlatform interoperability.

Migration path.

• From bshaffer/oauth2-server-php: likely the best case — near drop-in if APIs match; treat as a security-patch swap gated by a conformance test suite.
• From Passport: treat as a rewrite of token issuance, guard, scope middleware, revocation, and key handling while preserving DB schema where possible. Only justified by a hard constraint.
• Greenfield: do not start here. Integration cost exceeds the value of the fork's differentiators.

Compatibility. Verify PHP version support (8.1/8.2/8.3), PSR interface versions, and whether storage adapters assume Doctrine. Expect to supply your own caching layer for token lookups and a Composer replace/fork-and-vendor strategy if upstream goes quiet.

Sequencing.

1. Timeboxed spike (≤1 week) on a branch: one grant type end-to-end against Eloquent.
2. Threat model and RFC conformance checklist signed off by security.
3. Token store schema + indexing + expiry/cleanup job.
4. Grant-by-grant implementation behind feature flags.
5. Scope middleware and resource-server enforcement.
6. Conformance and negative tests (redirect-URI mismatch, replay, expired, revoked).
7. External security review — non-negotiable for an auth server.
8. Cutover with dual-read token validation and a rollback window.

Product decisions this informs. Grant types, scopes, and token lifetimes are product levers, not plumbing: scoped API access maps to pricing tiers, client credentials map to usage-based/B2B plans, refresh-token policy maps to session and seat rules. Decide these before the technical spike so the implementation isn't redesigned around the wrong product model.

Operational Impact

Maintenance. You own it. With 2 stars and no dependents there is no upstream patch cadence to lean on; assume fork-and-vendor within 12 months. Track PHP minor-version deprecations yourself and re-run conformance tests on every PHP upgrade. This belongs in the roadmap as an explicit line item, not a silent dependency.

Support. Effectively zero community support. Oro's community is CRM-focused, not OAuth-library-focused. Requires a named internal owner with real OAuth2 depth; bus factor of one is a genuine risk. No SLA, no vendor channel, no dependency a security team will accept without a waiver.

Scaling. Token storage is the bottleneck, not the library. Index on token hash and expiry, use Redis or another fast store for access-token lookups, batch/async cleanup of expired rows, and be explicit about revocation-propagation latency. Token introspection and refresh-token rotation add write load — capacity-plan for them up front.

Failure modes.

• Storage outage → total authentication outage across every protected surface. Needs a documented degradation policy (fail closed, with alerting).
• Clock skew / expiry-boundary handling → intermittent 401s that are painful to reproduce.
• Signing-key rotation without a grace window → mass token invalidation.
• Scope-escalation or redirect-URI matching bugs → security incident, not an outage.
• Refresh-token replay undetected → credential compromise with no telemetry unless you build it.

Ramp-up. Two to four weeks for a competent Laravel team to production-harden this package and its surrounding middleware, versus roughly two to four days with Passport. Engineers also need RFC-level OAuth2 fluency, because the library's abstractions are thinner than Passport's guards and will not protect them from protocol mistakes. Recommend a go/no-go on Passport before committing engineering time.

TPM recommendation. Treat this as a reference implementation and fallback, not the default. If we are on the Oro stack, adopt it and budget maintenance explicitly. If we are on Laravel or greenfield PHP, standardize on league/oauth2-server via Passport — same protocol, maintained upstream, ecosystem included. The decision criterion is 18-month total cost of ownership, not license price. Ask of leadership: approve a one-to-two-week evaluation spike against Passport, with the decision gated on TCO and security review, not on the zero license cost.