Openid Connect Laravel Package

Technical Evaluation

Architecture fit ronvanderheijden/openid-connect is a Laravel-native package that layers OpenID Connect provider capabilities onto an existing Laravel application — discovery document (/.well-known/openid-configuration), JWKS exposure, and the surrounding token/claim plumbing. Architecturally it sits as a thin HTTP + crypto adapter over the app's existing user model and auth guard, which is a good fit if the intent is to make a first-party Laravel app the identity provider (IdP) for sibling services. It is a poor fit if the requirement is to consume a third-party IdP (that is Socialite territory) or if the IdP must be a standalone, horizontally scaled service independent of the Laravel app lifecycle.

Integration feasibility High. The package is Composer-installable, publishes config/routes, and the surface area a TPM needs to sequence is small: config publish, route registration, key material generation, and claim mapping to the User model. The 1.2.1 fix is illustrative of the integration surface — scopes_supported in the discovery document is exactly the field a relying party (RP) reads at bootstrapping to decide which scopes to request. A malformed value here does not break the package's own tests so much as it breaks consumers, which is the classic integration-seam defect. That the fix landed as a patch within days is a positive signal about responsiveness and a caution about test coverage at the protocol-conformance boundary.

Technical risk

• Protocol conformance is the dominant risk. Discovery metadata is a contract with every RP in the estate. Field-level drift (scopes_supported, response_types_supported, id_token_signing_alg_values_supported) causes silent, hard-to-attribute consumer failures rather than loud ones. Budget for a conformance check against the OIDC discovery spec in CI, not just unit tests.
• Key management is under-owned. Signing key rotation, kid handling, and JWKS cache TTLs are operational concerns the package can support but not decide. Assign an owner before go-live.
• Version pinning. Pre-2.x versioning on a security-adjacent package means semver is a courtesy, not a guarantee. Pin exact versions and read every changelog.
• Bus-factor and governance. A single-maintainer package in the auth path is a standing risk; the 1.2.1 release (two external contributors on one PR) is mildly reassuring but does not change the structural picture.

Key questions

1. Are we building an IdP, or consuming one? If consuming, this is the wrong package and the evaluation should stop.
2. Which RPs will depend on our discovery document, and do we have their scope requirements enumerated?
3. Who owns signing key custody, rotation cadence, and JWKS propagation lag?
4. What is our conformance test story — is there an automated diff of the discovery document against the spec and against prior releases?
5. What is the exit plan if the package is abandoned — how much of our auth surface is package-specific versus standard?

Integration Approach

Stack fit Strong for Laravel 9/10-era applications on PHP 8.1+, particularly where the user store is already Eloquent and authorization decisions can reuse existing policies/gates. The package assumes it can own the well-known routes; confirm no reverse proxy, API gateway, or CDN in front of the app is already serving or rewriting /.well-known/*, which is a common and confusing collision.

Migration path Greenfield IdP: install, publish config, generate keys, register routes, map claims, then wire the first RP in staging. Brownfield (existing bespoke token endpoint): run the package's discovery/JWKS endpoints alongside the legacy issuer, point one low-risk RP at the new issuer, and only decommission the old path once token validation parity is proven across all RPs. Do not cut over the issuer value in place — changing iss invalidates every cached token and every RP's stored configuration.

Compatibility Verify explicitly: Laravel version constraint, PHP version, and the lcobucci/jwt (or equivalent) transitive dependency — JWT libraries have historically shipped breaking changes on minor bumps. Confirm compatibility with the firebase/php-jwt or web-token stack used elsewhere in the estate so we are not running two JWT implementations with divergent clock-skew and algorithm-allowlist behavior. Also confirm the fix in 1.2.1 matches the exact shape our RPs expect (array vs. space-delimited string) — OIDC specifies a JSON array, and RPs vary in how strictly they enforce it.

Sequencing

1. Pin and vendor 1.2.1; record the resolved dependency tree.
2. Stand up discovery + JWKS in a non-production environment; snapshot the document and diff it against the spec and against 1.2.0 to confirm the scopes_supported change is the only delta.
3. Generate and custody signing keys; document rotation runbook.
4. Integrate one internal, low-blast-radius RP; validate full authorization-code flow end to end, including token refresh and ID token claim verification.
5. Add a CI conformance gate on the discovery document before onboarding RP #2.
6. Roll out remaining RPs; only then retire legacy issuer paths.

Operational Impact

Maintenance Low routine burden — the package is small and the 1.2.1 delta is a one-line metadata correction. The real maintenance cost is not code upgrades but contract maintenance: every RP's assumptions about our discovery document and claim set. Treat the published discovery document as a versioned public API with a changelog and a deprecation policy, even though the package does not enforce one.

Support Support load will concentrate at two seams: RP onboarding (scope and claim mismatches) and key rotation windows. Both are predictable and should be pre-documented as runbooks rather than handled as incidents. Because the failure signature of the 1.2.1 bug class is "RP silently requests the wrong scopes," expect a long tail of misattributed bug reports pointing at RP teams before anyone suspects the IdP metadata.

Scaling Discovery and JWKS endpoints are static, cacheable, and trivially scalable — serve them with aggressive cache headers and consider fronting them at the edge. The scaling concern is the token endpoint: signing is CPU-bound and synchronous. Establish a baseline tokens/sec per app instance, and note that horizontal scaling of the Laravel app requires all instances to share the same key material and kid — this is the single most common way an otherwise-fine OIDC deployment falls over during an autoscale event.

Failure modes

• Metadata drift (the 1.2.1 class): malformed or stale discovery fields cause RP-side scope negotiation failures. Detection: automated diff in CI and a synthetic RP probe in production.
• Key rotation without JWKS propagation: RPs reject tokens signed with an unknown kid. Mitigate with overlap windows and published cache TTLs shorter than the rotation interval.
• Clock skew: token nbf/exp validation failures across hosts. Set and document an explicit leeway value.
• Upstream abandonment: no security patches. Mitigate by keeping the fork surface small and maintaining a tested internal fallback for discovery/JWKS.
• Route collision with gateway or existing .well-known handlers — fails loudly at deploy, but only if a smoke test hits the endpoint.

Ramp-up Estimate roughly one engineer-week to a validated first-RP integration for a team already fluent in OAuth2/OIDC, and two to three weeks if the team is learning the protocol on this package — the package hides the plumbing but not the concepts, and debugging a failed OIDC flow without protocol fluency is where timelines actually slip. Add half a week for key custody and rotation runbook authoring, which is organizational work rather than coding. Recommend one engineer own the IdP surface end to end (metadata contract, keys, RP onboarding) rather than distributing it, given how much of the operational risk is in cross-team contract discipline rather than in the code.