Keycloak Security Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for enterprise SSO: This package is a thin integration layer between a Symfony application and a self-hosted Keycloak realm. Its existence supports the decision "we do not build our own OIDC/SAML handshake, token refresh, role mapping, and logout flows" — we buy (or self-host) Keycloak and wire it in with a bundle like this instead.
• Roadmap commitment to enterprise readiness: Whether SSO/SAML, SCIM-style provisioning, and role-based access are v1 or v2 features. Adopting an integration layer now is what unblocks the "sells to IT/security buyers" milestone.
• Identity as a platform concern vs. per-app concern: Using Keycloak + a bundle moves auth out of each app and into a shared identity provider, which is a product architecture decision (multi-product single sign-on) rather than a coding one.
• Keycloak version as a supported-platform decision: v2.0.0 explicitly retargets the bundle at Keycloak 24. That converts "which Keycloak do we standardize on?" from an ops detail into a product compatibility statement — our IdP upgrade cadence and this bundle's upgrade cadence are now coupled, and Keycloak ships majors faster than this package does.
• Feature scope for roles and permissions: Keycloak realm/client roles become the source of truth for authorization; this determines whether we ship in-app role management UIs (a real feature cost) or delegate to the IdP admin console (cheaper, less polished, often acceptable for B2B).
• Which products get SSO first: Low-adoption, low-dependency packages like this one are best trialed on internal tools or a single design-partner tenant before being declared the standard for all applications.
• Stack-fit verification (critical gate): Despite the "Laravel/PHP" framing, this is a Symfony bundle (...SecurityBundle, NTI's IDCIKeycloakSecurityBundle). For a Laravel codebase this is not a drop-in dependency; the real decision is either "adopt Symfony for this service," "use a Laravel-native OIDC client," or "port the logic." That decision should be made deliberately, not by a developer who saw a package name.
• Open-source consumption policy: GPL-3.0 is copyleft. That is a product/legal decision, not an implementation detail — it affects whether this code can ship inside on-prem or distributed deliverables.
• Upgrade-and-pin policy for security-adjacent dependencies: v2.0.0 is a major bump whose only stated content is "adapting to Keycloak 24 and some minor corrections." A major version on an auth component means breaking changes with no published migration guide. The product decision is whether we accept owning that upgrade path (fork + diff review) or treat each release as a re-evaluation.

When to Consider This Package

Consider it when all of the following hold:

• The application is Symfony (not Laravel) and on a version compatible with the bundle's support matrix — confirm this in a spike, not in a planning doc. v2.0.0 was cut to track Keycloak 24, so validate against Keycloak 24 specifically, and check whether your Keycloak is newer (25+/26+) and therefore ahead of the bundle's tested target.
• You already operate, or have committed to operating, Keycloak as your identity provider. The bundle is glue for Keycloak specifically; it is not a general-purpose OIDC client.
• The deployment is internal, single-tenant, or self-hosted where GPL-3.0 obligations are easy to satisfy, or your legal team has explicitly cleared GPL for your distribution model.
• You need the boring-but-essential flows quickly: login redirect, token handling, role-to-ROLE_* mapping, logout. These are well-trodden paths and are exactly what such bundles compress.
• You can pin a version and own the fork. With 2 stars and 0 dependents, treat the maintainer's roadmap as nonexistent; your team is effectively the maintainer of last resort. Pinning now means pinning to a version that matches your Keycloak, not to "latest."
• You are using it as a reference implementation — reading how it wires Keycloak into Symfony's security firewall is genuinely useful even if you write your own 200 lines.
• New in v2.0.0: you are either greenfield (v2 is a clean starting point) or willing to fund an explicit v1 → v2 migration spike, because the major-version bump plus a one-line release note means the breaking changes are undocumented and must be read out of the diff.

Look elsewhere when:

• You are on Laravel. Use a Laravel-native OIDC/Socialite provider or a maintained OIDC client library; do not let stack mismatch get discovered mid-sprint.
• You need commercial support, SLAs, or a security-response process. Near-zero adoption means near-zero community scrutiny — no one else is finding the CVEs for you.
• You are shipping a closed-source or distributed product and GPL-3.0 has not been cleared. Copyleft obligations on a security layer are a bad place to discover a licensing problem.
• You need SAML, SCIM, MFA policy orchestration, or step-up auth beyond standard Keycloak flows — those are Keycloak-side or custom-work items, not bundle features.
• You are on a Keycloak version other than 24 and unwilling to align. The bundle now targets a specific IdP major; if your platform standard is "latest Keycloak," you will be perpetually behind or patching yourself.
• You need active maintenance signals: multiple recent releases, responsive issues, downstream dependents, a changelog with substance. v2.0.0 is one upstream-tracking release with a one-sentence note — a heartbeat, not a track record.

How to Pitch It (Stakeholders)

One-liner for executives: A small open-source adapter that lets a Symfony app delegate login and role checks to Keycloak — v2.0.0 re-targets it at Keycloak 24, which keeps it viable but also confirms it lags the IdP's release cadence; it shortens the path to "we support enterprise SSO," but it remains a low-adoption, GPL-licensed component we should pilot and potentially fork rather than standardize on.

For engineering leadership:

• The win: authentication is undifferentiated heavy lifting. This bundle removes the hand-rolled token, redirect, and role-mapping code that historically produces security bugs — exactly the code you do not want bespoke. v2.0.0 shows the maintainer is still tracking Keycloak's breaking changes, which is the single most important thing a glue library has to do.
• What changed: v2.0.0 ("Adapting to version 24 of Keycloak and some minor corrections") is a major version, so assume breaking changes — but none are documented. There is no changelog, no migration notes, and "minor corrections" is unspecified on a security-sensitive component. Treat the release as unverified until an engineer reads the diff.
• The honest caveats: 2 GitHub stars, 0 dependents, GPL-3.0. The release cadence is now visibly reactive to Keycloak majors — one release per IdP milestone, roughly a year apart — which means the safe operating model is "we pin, we watch Keycloak releases, we budget a fork-and-diff each time either side moves." That combination means no safety net: no community patch pipeline, no vendor to escalate to, and a license that constrains distribution. It also remains Symfony-specific, so it does not solve a Laravel problem.
• The recommendation: keep the timeboxed spike (2–3 days) on one non-critical service, and widen it slightly. Success criteria: login/logout/refresh works against Keycloak 24, Keycloak roles map cleanly to app roles, the v2 diff is small enough that one engineer can own a fork, and we can state in writing which Keycloak versions we support. If it passes, adopt v2 behind an internal abstraction so it can be swapped; if it fails, we have still learned our Keycloak integration shape and can implement it directly with a maintained OIDC library.
• The ask: not a budget line, but three decisions — (1) legal sign-off on GPL-3.0 in our distribution model, (2) agreement that "SSO" means Keycloak as the system of record, so we are not building role management UIs into every product, and (3) agreement that Keycloak 24 is our supported IdP baseline, since this bundle now defines compatibility in those terms and will not track every future Keycloak major on our timeline.