Weave Code
Keycloak Security Bundle Laravel Package
idci/keycloak-security-bundle
IDCI KeycloakSecurityBundle integrates Keycloak with Symfony security. It provides an authenticator and user provider for OpenID Connect/OAuth2 SSO, token validation, role mapping, and user provisioning, helping secure Symfony applications with Keycloak authentication and authorization.
Symfony bundle to easily setup security using Keycloak / OAuth
Frequently asked questions about Keycloak Security Bundle
- Can I use IDCIKeycloakSecurityBundle with Laravel?
- No. It is a Symfony bundle that registers a security factory, a firewall listener, and a user provider against Symfony's SecurityBundle, and Laravel has no equivalent firewalls, security factories, or UserProviderInterface. Porting it to Laravel means rewriting the factory and user provider as a custom guard plus middleware, at which point you have effectively written the package yourself. For Laravel teams it is useful mainly as a reference implementation for Keycloak claim and role mapping.
- How do I install and configure IDCIKeycloakSecurityBundle?
- Install it with Composer, enable the bundle in your Symfony kernel, and configure the Keycloak realm and client settings in your security configuration. You point it at your realm's OpenID Connect endpoints and attach the bundle's authenticator to the firewalls you want to protect. Check composer.json for the supported Symfony version range before upgrading, since patch releases do not signal new platform support.
- Which Symfony versions does this bundle support?
- It targets Symfony's SecurityBundle firewall and authenticator architecture, so it only runs in a Symfony application with the security component actively configured. Confirm the exact constraints in the package's composer.json, because a patch release like 2.0.2 implies no breaking API change but does not guarantee support for the newest Symfony major. Note that Symfony 6.3 and later ship native OIDC discovery and token handling that overlap with this bundle's job.
- How does token validation work for APIs and web apps?
- The bundle is a thin orchestration layer: it wires an OAuth2 client into Symfony's authenticator chain and relies on the underlying provider for the security-critical signature and token validation. That keeps the audit surface small but means you inherit the release cadence and any vulnerabilities of those dependencies. For API protection, each request must present a valid Keycloak-issued access token for the configured realm and client.
- How do I map Keycloak roles to Symfony roles and provision users?
- The bundle's user provider reads Keycloak realm and client roles from token claims and maps them onto Symfony security roles you define in configuration, so existing voters and access checks keep working. The same provider provisions local user objects from those claims, which saves you from writing custom lookup and creation code. The mapping assumes your Keycloak realm is set up with the expected realm and client role structure.
- How do I test a Symfony app secured with Keycloak?
- Unit-test your role mapping and voters in isolation, since that is your own code and the bundle's most valuable contribution is the claim-to-role translation. Integration testing needs a real or containerized Keycloak realm with the client and role configuration the bundle expects, because token validation depends on live endpoints and signing keys. Because it leans on Symfony's authenticator chain, you can also mock the token storage and authenticator in kernel tests. Do not treat a green suite as proof the newly added logout path is safe, since that code has little real-world exercise.
- Does the bundle support logout?
- Server-side user session logout handling was added in version 2.0.2, so signing a user out now invalidates the session instead of leaving it to you. That closes one of the more commonly cited gaps in earlier versions, but the code is fresh, security-adjacent, and has not been exercised by a meaningful user base. Verify the behavior against your Keycloak client's logout and post-logout redirect configuration before relying on it.
- Can I ship this package to production given its license?
- Be cautious. GitHub reports the license as NOASSERTION, meaning it could not detect a recognized license, so legal should read the actual LICENSE file and composer.json before you ship. Until that is cleared, treat the code as all rights reserved rather than assuming an open source license applies. This is a hard gate independent of how good the technical fit is.
- Is the project actively maintained?
- It moves slowly. Version 2.0.2 arrived after a long gap with documentation improvements and the new logout handling, which shows a maintainer is still present but not that the project has sustained velocity. Adoption is very low, with roughly 49 GitHub stars and no dependents, so expect little community support, third-party patching, or CVE attention. Also verify compatibility with Keycloak 22 and later, which changed default endpoints, admin APIs, and token claim shapes.
- What are the alternatives for Keycloak authentication in Symfony?
- Symfony 6.3 and later include native OIDC discovery and token handling, and knpuniversity/oauth2-client-bundle paired with a Keycloak provider covers most of the same ground with far more community scrutiny. This bundle's advantage is that it packages Keycloak wiring, role mapping, user provisioning, and, since 2.0.2, logout into one integration. Weigh that convenience against a much smaller user base and a thin maintenance record.
Weaver
How can I help you explore Laravel packages today?