Download the PHP package bannerstop/keycloak-bundle without Composer

bannerstop/keycloak-bundle

Symfony integration of bannerstop/keycloak: single sign-on with Keycloak for the Symfony security component.

• Browser login (authorization code flow with PKCE) as an authenticator, including the entry point
• Bearer tokens for stateless API firewalls
• Logout that also ends the Keycloak session
• Role mapping from realm roles, client roles and groups
• Works without a user table (stateless KeycloakUser) or with your own users (UserProvisioner)

Versions

Installation

Without Symfony Flex, register the bundle in config/bundles.php:

Import the routes (/login/keycloak and /login/keycloak/callback), e.g. in config/routes/bannerstop_keycloak.yaml:

In Keycloak, register https://your-app.example/login/keycloak/callback as redirect URI and your logout target as post logout redirect URI. See the core README for the full client setup.

Configuration

directory gives the user directory (UserDirectory, admin REST API) its own confidential client. We recommend it: create a client with only Service accounts roles enabled and assign realm-management → view-users to its service account, so that the login client has no admin API rights. Without directory, the login client is used for both and needs the service account and view-users itself.

cache (default cache.app) caches the discovery document and the signing keys. http_client, request_factory and stream_factory take service ids if you do not use symfony/http-client.

Security

Your own users

By default users only live in the session (KeycloakUser, identified by the Keycloak subject) and are served by bannerstop_keycloak.user_provider.

To use your own user entity instead, implement Bannerstop\KeycloakBundle\User\UserProvisioner. After every successful login and every accepted bearer token, the bundle calls provision() with the verified identity and the mapped roles; the user it returns is the authenticated user. Link accounts by the Keycloak subject, not by e-mail address, which can change:

user_provisioner is an option of this bundle (not of Symfony itself) and takes the service id of your provisioner. With autowiring, the id is the class name:

The firewall then uses your usual entity provider instead of bannerstop_keycloak.user_provider:

The provisioner hands Symfony the user at login; on every following request Symfony reloads it through the firewall's provider. That provider must therefore return the same entity class.

remember_me on the firewall applies to Keycloak logins as well. It needs a user with a password property or other signature_properties, so it works with your own users, not with the session-only KeycloakUser.

Ending sessions with Keycloak

Logging out of Keycloak, or of another application, does not end the Symfony session by itself. The bundle closes that gap in two ways:

• Back-channel logout: Keycloak posts a signed logout token to /login/keycloak/backchannel-logout when a session ends. The bundle verifies it and records the ended Keycloak session in the cache (cache, default cache.app, which must be shared by all web servers). In the Keycloak client set Backchannel logout URL to https://your-app.example/login/keycloak/backchannel-logout and turn on Backchannel logout session required. The route must be reachable without a login; the ^/login access rule above already covers it.
• Session check (session.check_interval): every N seconds the refresh token of the session is redeemed. Once Keycloak refuses it (logout elsewhere, user disabled, SSO session expired), the session ends. If Keycloak is unreachable, the session is kept.

On the next request after its Keycloak session ended, a session is logged out (including the remember-me cookie): pages redirect to themselves, so the firewall's entry point asks for a new login, and XHR/JSON requests get a 401. Only sessions that came from a Keycloak login are checked.

Keycloak does not always send a back-channel call for every session, e.g. when an administrator signs a user out of all sessions. Keep check_interval switched on as a safety net; 300 seconds is a good start.

Login errors

A failed login redirects to failure_path. AuthenticationUtils::getLastAuthenticationError() then returns an exception whose message key is one of keycloak.login.state_mismatch, .cancelled, .provider_error, .invalid_token or .not_allowed. Translate them in the security domain.

Services

License

MIT, see LICENSE. Security issues: see the core package's security policy.