Oauth Server Bundle Laravel Package

Technical Evaluation

Architecture fit. This package owns the authorization-server tier of our OIDC surface, sitting between Laravel's auth layer and downstream clients (SPAs, mobile, third-party RPs). Release 6.0.0 is a conformance-hardening change: nonce and auth_time move from "the integrator's problem" to first-class attributes of the authorization code, so the token endpoint can mint a correct id_token without out-of-band state. That is the right architectural direction — it removes a class of homegrown workarounds — but it is delivered as a major version with an interface expansion, not a patch.

Integration feasibility. Moderate. The feature work is additive; the delivery is not. Three things break or require action in lockstep:

1. AuthCodeInterface gains setNonce()/setAuthTime(). Any local class implementing that interface fatals on upgrade until both methods exist. This is a hard compile-time break, not a deprecation.
2. OAuthStorage::createAuthCode() changes signature to accept and persist the nonce. Any subclass or wrapper overriding it violates LSP and will error.
3. Doctrine mappings (ORM/MongoDB/CouchDB) add nullable nonce and auth_time fields — a schema change on whichever backend we actually run.

Technical risk. Rated medium-high, driven by two silent failure modes rather than loud ones:

• Nonce loss through consent. The nonce now survives the consent round-trip via a hidden form field. Any custom consent view that does not render that field drops the nonce with no error — the token request simply produces an id_token without a nonce claim. OIDC replay protection degrades quietly and conformance suites fail later, in staging or at a customer.
• auth_time is deliberately left to the application. The package only carries the value; it does not know when the user authenticated. If our login flow never stamps it, auth_time stays null, max_age requests cannot be honoured, and clients relying on re-authentication freshness get a claim they cannot trust. This is a required application-side change that the release notes explicitly hand back to us — easy to miss in a version bump.

Secondary risks: schema migration on a potentially large auth_codes table (nullable, so low risk, but non-zero on MongoDB/CouchDB where index definitions may need review), and snapshot-style tests asserting exact id_token claim sets will need updating.

Key questions.

• Which persistence backend are we actually on — Eloquent adapter, Doctrine ORM, MongoDB, or CouchDB? The mapping changes only matter for the Doctrine path; the interface change matters regardless.
• Do we have any in-house AuthCodeInterface implementation or OAuthStorage subclass, or are we on the shipped defaults?
• Is our consent screen a stock view or customised Blade? Who owns it?
• Where in the login flow can we reliably capture authentication time, and does that survive SSO/session-restore paths where "authenticated now" is false?
• Do any downstream RPs validate nonce or request max_age today? If none do, the urgency drops but the conformance debt remains.
• Is there a reason to take 6.0.0 now versus holding on 5.x until our next scheduled maintenance window?

Integration Approach

Stack fit. Standard Laravel/PHP consumption — Composer dependency, service provider registration, config publish. The only meaningful coupling points are the storage adapter and the consent view. If we are on the framework's default storage, the surface area is small and contained; if we have a custom adapter, treat this as a refactor, not an upgrade.

Migration path.

1. Audit: grep for AuthCodeInterface, OAuthStorage, createAuthCode across the codebase and any first-party packages.
2. Add setNonce()/setAuthTime() to local implementations; align createAuthCode() signatures.
3. Ship the schema migration for nullable nonce/auth_time on the backend in use; backfill is unnecessary (nulls are semantically "unknown").
4. Update consent templates to render and preserve the hidden nonce field.
5. Stamp auth_time in the login/authentication handler and thread it into the auth code before redirect.
6. Add a regression test asserting the nonce round-trips request → consent → token → id_token claim.

Compatibility. Client-facing impact is additive — id_token gains optional claims, which well-behaved RPs ignore. The risks are internal: interface implementors and overridden storage methods. One deploy-window nuance: authorization codes minted before the upgrade carry no nonce, so token requests completing after it cannot emit a nonce claim for them. With a short code TTL this self-resolves; if TTL is long, plan a drain or accept a brief window of nonce-less tokens.

Sequencing. Do not bundle this with unrelated auth work. Order: (a) audit and code changes on a branch, (b) schema migration applied in staging and verified against the real backend, (c) consent template + auth_time stamping, (d) conformance/regression run, (e) production deploy inside a low-traffic window followed by a code-TTL drain. Treat it as a security-relevant change and give it a deliberate slot rather than letting it ride a routine dependency bump.

Operational Impact

Maintenance. A major version whose headline is an interface expansion signals the OIDC surface is still actively evolving upstream — expect further majors around claims handling, PAR, or CIBA. Pin the version explicitly, watch the release feed, and budget recurring upgrade capacity rather than treating this as a one-off.

Support. The hidden-form-field mechanism is the highest-probability support driver: "why is nonce missing from the id_token?" will be a recurring ticket whenever a theme or consent view is edited by someone unaware of the contract. Write a short runbook entry and add a test that fails loudly if the field disappears.

Scaling. Negligible. Two nullable columns on the auth-code table (or two optional document fields) add trivial storage; the real consideration is the existing retention/cleanup job — confirm it still runs correctly against the widened schema and that Mongo/Couch index definitions are reviewed if we are on those backends.

Failure modes.

• Silent nonce drop — no exception, just a missing claim and weakened replay protection.
• Unstamped auth_time — null or stale claim; max_age silently unenforced.
• Deploy-window code mismatch — pre-upgrade codes producing post-upgrade tokens without a nonce.
• Interface fatal — the one loud failure, caught at boot or first request, which is the good case.

Ramp-up. Roughly one to two engineer-days for someone already fluent in the authorization-code flow: interface and storage changes are mechanical; the consent template and auth_time stamping need judgement about where authentication genuinely occurs. The expensive part is not the code — it is confirming the nonce survives every consent variant and that auth_time reflects real re-authentication rather than session restoration.