Openid Connect Laravel Package

Technical Evaluation

Architecture fit. The package is Laravel-native rather than a generic PHP OIDC client: it hooks into the framework's guard/user-provider model, ships environment-driven configuration, and resolves the discovery document at runtime instead of hard-coding endpoints. That is the right shape for a conventional server-rendered Laravel application that currently owns password storage and wants to delegate authentication to an enterprise IdP (Entra ID, Keycloak, Okta, HelseID-style providers). It is a poorer fit for stateless API/SPA consumers (Sanctum tokens, mobile clients) and for multi-tenant apps where the issuer varies per customer — the described multi-provider config helps, but per-tenant issuer routing would likely need custom work.

Integration feasibility. Low-to-moderate. The happy path is composer require, publish config, set issuer/client id/secret/redirect URI, map claims, protect routes with the guard. Real effort sits outside the package: account linking for existing users, just-in-time provisioning policy, deprovisioning, and logout. Notably absent from the stated feature set are RP-initiated logout, refresh tokens / silent re-authentication, and token revocation — each of which is a standard enterprise requirement and would need to be built or accepted as a gap.

Technical risk. The dominant risk is not code quality but adoption: 1 star, 0 dependents, no downstream validation, and a single maintainer organisation (itk-dev, a Danish public-sector IT shop). For a component that sits directly on the authentication path, that means no third-party security review, no CVE-watching ecosystem, and an unknown backward-compatibility policy. Secondary risks: correctness of ID-token validation (signature, iss, aud, exp, nonce, state), JWKS retrieval/caching and key rotation, and the safety of automatic claims-to-user mapping — silent user creation or overwriting from an unverified claim is an account-takeover vector if misconfigured.

Key questions.

1. Does it validate the full ID token (signature against JWKS, issuer, audience, nonce, clock skew) or delegate to a vetted library?
2. Is PKCE supported and is state enforced on callback?
3. How are JWKS and the discovery document cached, and what happens on cache miss with the IdP unreachable?
4. What are the supported Laravel/PHP version constraints, and what is the BC/versioning policy?
5. Does it support refresh tokens, RP-initiated logout, and back-channel/session-expiry handling?
6. Are there known production users, and is there a public CI/test suite and security disclosure process?
7. What is the account-linking rule — sub + iss, or email (and is email required to be verified)?
8. Does it conflict with Socialite, Sanctum, Passport, Breeze/Jetstream, or Filament's auth panels?

Integration Approach

Stack fit. Assumes a modern Laravel (8.x–11.x range to be confirmed against composer.json) on PHP 8.x, session-based auth, and an IdP exposing a compliant discovery endpoint. It composes cleanly with existing local auth: OIDC can be introduced as an additional guard while the default web guard stays on passwords, which makes a staged rollout possible without a flag-day cutover.

Migration path.

1. Spike (non-prod) — register a client at the IdP, wire the package against a test tenant, confirm discovery, redirect, callback, and claim payload.
2. Schema and linking — add oidc_sub and oidc_issuer columns with a unique composite index; define the linking policy explicitly (prefer sub; link by email only if email_verified is true, and require an explicit first-login confirmation).
3. Single route — enable the guard on one low-risk, internal-facing route; keep password login for everyone.
4. Provisioning and deprovisioning — decide JIT-create vs. pre-provision; document what happens when a user is disabled at the IdP but the local row persists (session invalidation is not automatic).
5. Default guard flip — make OIDC the default for the target population, retain a break-glass local admin path.
6. Decommission — remove password reset flows and credential columns only after a full cycle of successful logins.

Compatibility. Verify the Laravel/PHP support matrix against the app's pinned version, whether the package pulls in Socialite or a league/oauth2-* client (that determines upgrade coupling), and whether it overrides or wraps the Eloquent user provider. Confirm the app has no competing auth panel (Filament, Nova, Jetstream) that registers its own guard.

Sequencing. IdP client registration and scope agreement → package install and config → user mapping contract → provisioning/deprovisioning → logout and session semantics → observability (auth event logging) → cutover. Each step is independently reversible until step 5.

Operational Impact

Maintenance. Budget a recurring, explicit line item: pin the version, review every diff before upgrading (this is authentication code), and assume you may need to fork. A realistic estimate is 1–3 engineer-days per quarter for upgrades and IdP-side changes, plus one-off effort if you must add logout or refresh-token support yourself.

Support. No commercial support and a small issue tracker. The team must own an internal runbook covering: IdP outage behaviour, how to grant emergency local access, how to rotate client secrets, and how to debug a failed callback (state mismatch, clock skew, redirect URI mismatch, missing claim).

Scaling. Runtime cost is trivial — one redirect plus a token and userinfo call per login. The scaling concern is dependency, not throughput: latency on the IdP's token endpoint and availability of the discovery document become part of your login path. Cache the discovery document and JWKS with a TTL and a stale-on-error fallback so a brief IdP metadata blip does not lock everyone out. Do not call userinfo on every request; map claims into the session or local user at login.

Failure modes.

• IdP unavailable → total login outage for OIDC users (mitigate with break-glass local admin).
• Discovery/JWKS unreachable at boot or first login → hard failure if fetched synchronously without cache.
• IdP key rotation with stale JWKS → signature validation failures across the fleet.
• Clock skew → intermittent exp/iat rejections, hard to reproduce.
• Claim drift (renamed or missing claims) → null fields, duplicate accounts, or login loops.
• Non-sticky load balancing or short session lifetime → state/nonce loss on callback.
• Redirect URI mismatch after a host or environment change → loop back to login.
• Misconfigured email-based linking → account takeover.

Ramp-up. A Laravel developer with no OIDC background needs roughly 1–2 days to be productive, most of it on OAuth2/OIDC concepts (authorization code flow, state/nonce, claims vs. scopes) rather than on this package's API. A TPM should also schedule a security review of the token-validation path before production, and record the claims contract as a written interface between the IdP team and the application team — that document, not the package, is what will govern future breakage.