Laravel Keycloak Web Guard Laravel Package

Product Decisions This Supports

• Enterprise SSO / identity roadmap. This package is the Laravel-side Keycloak (OIDC/OAuth2) integration: discovery, authorization-code flow, token handling. It underpins the "SSO for enterprise customers" roadmap item and any self-hosted / on-prem IdP offering, without asking the team to hand-roll OIDC.
• Build vs. buy vs. integrate. For teams that have standardized on Keycloak, this is the "integrate" option: it removes a custom auth client from the backlog and turns IdP work into configuration plus realm setup, rather than a multi-sprint crypto-and-protocol project.
• Security and compliance posture. v3.4.0 stops leaking Authorization headers, client_secret, authorization codes, tokens, and Guzzle exception messages into logs; only exception class, method, URL (sans userinfo), query, fragment and HTTP status are recorded. That is a direct enabler for log-hygiene requirements in SOC 2 / ISO 27001 / GDPR reviews and for passing customer security questionnaires on credential handling.
• Operational reliability of login. The fix for logging network failures without a response (DNS, connect, timeout) removes a crash path in exactly the condition (IdP unreachable) where auth is already degraded — fewer hard 500s during IdP incidents.
• Debuggability vs. secrecy trade-off. Preserving the original exception via getPrevious() on discovery failures keeps root-cause visibility for support and on-call while keeping sensitive payloads out of logs — a decision point for how much auth detail support staff get.
• Platform support matrix. Guzzle ^7.0 || ^8.0 (Guzzle 6 dropped) defines the supported dependency envelope; it gates whether this can ship on the current Laravel/PHP baseline and sets the dependency-modernization timeline.
• Maintenance confidence. Added PHPUnit/Testbench suite and CI across Guzzle 7 and 8 signals a maintainable dependency rather than an unowned integration — relevant to buy-vs-build and to any "can we rely on this for a revenue-critical login path" decision.
• Use cases served: B2B customer SSO, internal workforce apps behind a corporate IdP, multi-realm / per-tenant identity setups, and on-prem or data-residency-constrained deployments where a managed IdP is not acceptable.

When to Consider This Package

Consider it when:

• The organization (or a key customer) has chosen Keycloak as the IdP, and you need OIDC authorization-code flow in a Laravel app.
• You need self-hosted or on-prem identity, or data-residency constraints rule out Auth0/Okta/Cognito.
• You are running multi-realm / per-tenant identity and want discovery handled for you.
• Secret hygiene in logs is a hard requirement — regulated environments, customer security reviews, or an existing incident involving leaked tokens.
• You are on a modern Guzzle (7 or 8) and current Laravel/PHP; the tested, CI-backed path is the reason to adopt now rather than fork.
• You want a small, single-purpose dependency rather than a broad auth framework.

Look elsewhere when:

• You are standardized on a managed IdP (Auth0, Okta, Entra, Cognito) — use that vendor's SDK or the corresponding Socialite provider instead.
• You need SAML rather than OIDC.
• You require full Keycloak Admin REST API management (user/role/realm provisioning) — this covers the client auth flow, not admin surface; plan a separate integration.
• You are pinned to Guzzle 6 or an older Laravel/PHP baseline — v3.4.0 dropped Guzzle 6, so upgrading the HTTP client is a prerequisite.
• You need only lightweight first-party auth — introducing an external IdP is over-engineering.

How to Pitch It (Stakeholders)

To executives: This is the piece that lets us offer enterprise-grade single sign-on without building and maintaining an OIDC client ourselves. Customers who run their own identity provider — common in regulated, on-prem, and larger B2B accounts — can be onboarded through configuration instead of custom engineering. The new release materially improves our security story: credentials, tokens, and secrets no longer reach our logs, which is the kind of finding that stalls enterprise security reviews. It also makes login more resilient when the identity provider has an outage, and it ships with an automated test suite and CI, so it is a supported dependency rather than a bespoke liability. The main migration cost is a HTTP client upgrade off Guzzle 6.

To engineering: v3.4.0 is a security-and-hardening release. Logging of Keycloak request/response headers and bodies is removed (Authorization, client_secret, authorization codes, tokens), and Guzzle exception messages are no longer logged — only exception class, method, sanitized URL, and HTTP status. The network-error-without-response logging path no longer throws. Discovery failures now chain the original exception via getPrevious(), so we keep root cause without sensitive payloads. Guzzle support is ^7.0 || ^8.0; Guzzle 6 is dropped — treat this as the breaking change and audit composer.lock and transitive constraints before upgrading. PHPUnit/Testbench tests and CI now run against both Guzzle 7 and 8, so we get a verified upgrade path going forward.