Openid Connect Php Laravel Package

Technical Evaluation

Architecture fit. jumbojett/openid-connect-php is a deliberately thin OpenID Connect Relying Party: one primary class (OpenIDConnectClient) that performs discovery, authorization-code redirect, code-for-token exchange, ID token signature validation against the IdP's JWKS, and a userinfo call. It owns no session, no routing, no config, no user model, and no persistence. That is the right shape for a Laravel codebase: it slots in as an implementation detail behind an adapter you own (App\Auth\Oidc\...), and your service provider, config, routes, middleware, claim mapper, and user-provisioning logic stay yours. It is a poor fit if you want it to be the identity layer — it has no multi-tenant IdP registry, no role mapping, no SCIM/provisioning, no logout orchestration, and no token lifecycle management.

Integration feasibility. Composer-installable, no Laravel coupling to unwind, so baseline integration is small: a config file, a service-provider binding, two routes, a controller pair, a claim→user mapper, and tests. Two friction points drive the real estimate:

• Session coupling. The library persists state, nonce, and PKCE verifier in native PHP session storage by default. Under Laravel that collides with non-file session drivers, stateless/API contexts, and multi-node deployments. Expect to either force a shared session driver or inject Laravel's cache/session via subclass or a delegating wrapper — confirm the injection hooks exist in the version you pin (HTTP client abstraction has historically been curl-centric).
• Framework glue is yours. No service provider, no facade, no published config, no Laravel-facing docs. Everything above the library is first-party code and first-party test debt.

Effort for a conventional web app with one IdP: 8–12 engineer-days end to end (spike 1–2, wrapper 1, claim mapping + existing-user migration 2–4, security review 1–2, tests 2, rollout 1), plus review.

Technical risk.

Key questions.

1. Which IdPs must be supported at launch and in 12 months — one enterprise IdP, or per-tenant arbitrary issuers? (The latter turns this into a registry problem the library does not solve.)
2. Is the requirement browser SSO only, or also API/mobile tokens? If the latter, this is the front door, and Sanctum/Passport still issues your tokens.
3. Do we need refresh tokens, RP-initiated/back-channel logout, or session-bound tokens? Answer determines adopt-vs-alternative.
4. What session driver runs in production, and is it shared across nodes?
5. Compliance regime (SOC 2 / ISO 27001 / HIPAA) — does a single-maintainer dependency need a documented exception?
6. Who is the named internal owner, and what is the maximum acceptable patch latency after an advisory?
7. Is breaking-glass password login required during IdP outages?

Integration Approach

Stack fit. Laravel 10/11/12 on PHP 8.1+ (verify the pinned version's PHP constraint). Coexists cleanly with Socialite for consumer social logins and with Sanctum/Passport for API tokens — this library is the enterprise-SSO front door only. It does not conflict with existing middleware; the callback route sits on web for session access.

Migration path. Ship behind a flag and in parallel with existing auth:

1. Spike (branch): composer require jumbojett/openid-connect-php:<pinned>, one IdP (Entra ID / Okta / Keycloak), happy path plus one tampered-token test. Kill or confirm in 2 days.
2. Wrapper: config/oidc.php (issuer, client id/secret, redirect URI, scopes, claim mapping, clock skew), OidcServiceProvider binding a factory, cache-backed JWKS/discovery store.
3. Routes: GET /auth/oidc/redirect and GET /auth/oidc/callback, named, rate-limited, with redirect_uri built from route() under forced HTTPS.
4. Identity mapping: oidc_identities(provider, issuer, subject, user_id, timestamps, unique) — key on iss+sub, never email. Just-in-time user creation off configurable claims; explicit linking flow for pre-existing password users (verify-then-link, never silent merge by email).
5. Shadow mode: run beside the current login for 1–2 weeks, log claims and outcomes, diff against expectations.
6. Cutover per tenant/user cohort, password login retained as break-glass with alerting on its use.

Compatibility. Requires a shared session driver (Redis/DB, not file) if you rely on the library's state handling; behind load balancers, verify X-Forwarded-Proto/host handling so redirect_uri matches exactly at the IdP; set Secure/SameSite=Lax cookies; set explicit iat/exp clock-skew tolerance; confirm discovery and JWKS are cached rather than fetched per request.

Sequencing. Security review of the validation path should gate the shadow-mode exit, not the spike — you need working traffic before the review is meaningful. Keep the claim mapping behind an interface so that if you later swap to a PSR-18-native alternative (e.g. facile-it/php-openid-client) the blast radius is one class, because every call site goes through your adapter. That optionality is the main reason to accept the maintenance burden of a wrapper for a 700-star single-class library.

Operational Impact

Maintenance. You own a thin auth wrapper: budget roughly 1 engineer-week per quarter for dependency bumps, advisory triage, IdP metadata/certificate rotations, and test upkeep. Standing controls: pinned version, composer audit and composer outdated in CI, Dependabot/Renovate on the package, and a documented fork procedure (single-class, Apache-2.0 — forkable in hours, which materially de-risks the low-maintainer-velocity profile).

Support. No vendor support; community and upstream issues only. Define a named internal owner and a tier-1 escalation path: authentication failure is a full login outage for SSO users, so it belongs in the top tier alongside the database. Have a documented break-glass path (password login or admin-issued magic link) that does not depend on the IdP.

Scaling. The RP flow itself is negligible load. The cost centres are outbound HTTP: discovery and JWKS fetches (cache with ~1h TTL plus background refresh — uncached fetches add latency on every login and can trip IdP rate limits, especially under a login stampede), and the token endpoint round trip (commonly 100–500 ms). Reuse a configured HTTP client with connect/read timeouts and bounded retries; never hold a DB transaction across the token exchange; keep the callback handler idempotent so retries are safe.

Failure modes and runbook.

Instrument the callback path with structured logs (issuer, outcome, latency, failure class — never tokens or PII) and an alert on callback error rate.

Ramp-up. An engineer who knows OAuth 2.0/OIDC needs about half a day with the wrapper plus an internal doc containing the sequence diagram, the claim contract, and the failure-mode table. Without that background, budget 2–3 days of reading plus a paired review — do not let the library's "minimalist" framing substitute for understanding the authorization-code + PKCE + ID-token-validation flow, because that knowledge is what the security review will test.

Recommendation. Adopt, wrapped, pinned, and cached — but scope it as a browser SSO relying party for a small number of known IdPs. Escalate to a PSR-18-native alternative if the roadmap requires multi-tenant arbitrary issuers, back-channel logout, refresh-token management, or evidence-grade library provenance; the wrapper boundary keeps that switch to roughly 1–2 engineer-days.