Php Openid Client Laravel Package

Product Decisions This Supports

• Build vs. buy on the authentication core: buy. OpenID Connect is a security-sensitive spec surface (ID token signature/encryption validation, JWKS rotation, nonce/state, clock skew, issuer discovery). Hand-rolling this in a Laravel app is a multi-week effort with a permanent security-maintenance tail. This package is a thin, spec-literate client layered on web-token/jwt-framework (a well-maintained crypto library) and modelled on the widely trusted node-openid-client. The decision it supports is: adopt a library for the protocol, spend our engineering budget on the product-specific glue.
• Enterprise/B2B SSO roadmap unblock. If the product roadmap includes "log in with the customer's IdP" (Okta, Entra ID, Keycloak, Auth0, Ping), a complete OIDC relying-party implementation is table stakes. This package covers Authorization Code / Implicit / Hybrid, UserInfo, request objects, aggregated and distributed claims — i.e. the flows enterprise buyers actually ask about in security questionnaires.
• Multi-tenant "bring your own IdP" as a product feature. Dynamic Client Registration (OIDC DCR + RFC 7591/7592) plus read/update/delete means tenant onboarding can be automated instead of hand-configured. That converts an ops ticket into a self-serve flow — a genuine product differentiator, not just plumbing.
• Token lifecycle for API surfaces. RFC 7662 introspection and RFC 7009 revocation let us validate and kill tokens at the edge (API gateway, internal service auth) rather than trusting long-lived local sessions. This is a prerequisite for any "log out everywhere" or "revoke a compromised integration" feature we would otherwise have to invent.
• High-assurance / regulated verticals. JAR, JARM, MTLS-bound tokens, private_key_jwt and client_secret_jwt client authentication are exactly what financial, health, and public-sector IdPs demand. Supporting these in-house is out of scope; supporting them via this package is a configuration exercise.
• Scoping honesty — this is a PHP package, not a Laravel package. There is no service provider, no config file, no guard, no facade, no published migrations. The PSR-15 middleware set (SessionCookie, ClientProvider, Callback, UserInfo) is largely inert inside Laravel, which has its own HTTP kernel. The decision this drives is therefore "adopt the client services and budget for a ~1-week Laravel adapter (service provider, cache bindings, custom guard/user provider, callback controller, tests)" — not "composer require and ship."
• Explicit non-goals. It is a client (relying party). It does not make us an identity provider (that is Passport / Keycloak / Ory), and it does not replace Laravel Socialite for consumer "Sign in with Google" flows where a first-party driver already exists.

When to Consider This Package

Adopt when most of these hold:

• The IdP is an OIDC provider that isn't already covered by a maintained Socialite driver, or the flow needs capabilities Socialite doesn't expose (introspection, revocation, dynamic registration, request objects, private_key_jwt).
• The integration is security-relevant enough that we want a spec-complete client rather than a hand-rolled JWT check — and we're willing to own a small adapter layer in our own codebase.
• We can satisfy the platform requirements: PHP 8.2+ (1.0.0 dropped 8.1), PSR-18 HTTP client + PSR-17 factories + PSR-7 messages (Laravel/Guzzle already provides these), and the gmp extension on every environment — verify this against hosting/CI images, since missing gmp can be an infrastructure-level blocker rather than a code fix.
• We will implement the documented production hardening from day one: PSR-16 caching for issuer metadata and JWKS. Laravel's cache repository is PSR-16 compatible, so this is a low-friction win — but skipping it means a network round-trip to the IdP on every request.
• We accept the vendor-risk profile with mitigations in place (version pinning, an internal fork path, dependency review in CI).

Look elsewhere when any of these hold:

• Commodity social login only — Google/Apple/GitHub/Facebook. Laravel Socialite is the lower-cost, lower-risk answer. Don't introduce a spec-complete OIDC client for a button that says "Sign in with Google."
• We need to issue tokens, not consume them — that's Passport, or better, an off-the-shelf IdP (Keycloak, Ory, Auth0, WorkOS). Owning an IdP is a staffing decision, not a library decision.
• SAML is in scope. This package does nothing for SAML; enterprise buyers usually need both, so plan for a separate SAML path (or buy a managed broker).
• Risk tolerance for a low-adoption dependency on the auth path is near zero. The signals are thin: ~48 stars, listed dependents at zero, and a composite score around 18/100. Treat this as a due-diligence gate, not a red flag to wave away — mitigate with a wrapper interface we control, a pinned version, and a documented exit path, or choose a managed auth vendor instead.
• The team cannot own a custom guard. If nobody has bandwidth to build and maintain the Laravel glue, a managed identity product will be cheaper in total cost of ownership than a free library plus adapter plus ongoing protocol upkeep.
• Diligence item — confirm before committing: PKCE support is not enumerated in the README's feature list. If public/mobile clients or a strict IdP are in scope, verify PKCE (S256) is supported or add it in the adapter. Also confirm the 0 dependents signal reflects real adoption rather than an artifact of the package registry, and check release cadence (the changelog shows disciplined releases, including a 1.0.0 with a documented JWT-library major upgrade — a good sign of active stewardship).

How to Pitch It (Stakeholders)

For executives (one paragraph): Enterprise customers increasingly refuse to let us hold their users' passwords — they require login through their own identity provider. Meeting that requirement means implementing OpenID Connect, a security standard where a subtle mistake becomes a breach headline. This library gives us a complete, standards-compliant implementation for free, backed by the same cryptography library the PHP ecosystem already trusts. The decision is not "adopt a library" — it's "spend roughly a week of engineering on integration instead of months building and permanently maintaining authentication cryptography." It unblocks the B2B/enterprise segment and gives us token revocation and introspection, which are prerequisites for the security guarantees buyers ask for in procurement reviews.

For engineering (the honest version): This is the right core for OIDC relying-party work: it covers Auth Code / Implicit / Hybrid, ID token signing and encryption, UserInfo, request objects, dynamic client registration, introspection, revocation, and the FAPI-adjacent drafts (JAR, JARM, MTLS). It is PSR-native and framework-agnostic, which means we build the Laravel layer ourselves — a service provider binding the issuer/client services, PSR-16 cache wiring for metadata and JWKS (non-negotiable in production), a callback controller, and a custom guard/user provider. The bundled PSR-15 middleware is not useful under Laravel's kernel; don't budget for it.

Cost and risk, stated plainly: ~3–5 engineering days for the adapter plus tests, one infrastructure check (gmp extension and PHP 8.2+ on all environments), and one diligence question (PKCE support for public clients). The dependency-risk profile is the weakest part of the case: small community, negligible listed dependents. We mitigate by hiding it behind our own IdentityProviderClient interface, pinning the version, and keeping the integration surface small enough that swapping to a managed vendor or an alternative client is a contained piece of work rather than a rewrite.

Recommendation: Adopt behind an internal abstraction, as a scoped spike on the enterprise-SSO epic — not as a broad platform mandate. Validate it against one real IdP end-to-end (discovery → authorize → callback → claims → refresh → introspection) before committing the roadmap to it.