Weave Code
Laravel Keycloak Web Guard Laravel Package
vizir/laravel-keycloak-web-guard
Laravel authentication guard that signs users in to your web app through Keycloak. It handles login, logout, token refresh, and role-based route protection, delegating identity to Keycloak via OpenID Connect with minimal configuration and no custom auth code to maintain.
Simple Keycloak Guard to Laravel Web Routes - https://packagist.org/packages/vizir/laravel-keycloak-web-guard
Frequently asked questions about Laravel Keycloak Web Guard
- What is vizir/laravel-keycloak-web-guard and what does it do?
- It is a Laravel authentication guard that signs users in to server-rendered web applications through Keycloak using OpenID Connect. It plugs into Laravel's native auth extension points as a custom guard plus user provider, handling login, logout, token refresh, and role-based route protection. The intent is to delegate identity to Keycloak with minimal configuration and no bespoke auth code to maintain. It is aimed at monolith-style apps using Blade, Livewire, or Inertia with a session cookie as the auth carrier.
- How do I install and configure laravel-keycloak-web-guard?
- Install it with Composer, publish the package config, and set environment variables for the Keycloak base URL, realm, client ID, client secret, and redirect URI. Then register the custom guard and user provider in config/auth.php and attach the package middleware to your web route group. The integration surface is deliberately small, which keeps the blast radius of adoption low. Most of the effort goes into getting the Keycloak client configuration right rather than into Laravel wiring.
- Which Laravel and PHP versions does laravel-keycloak-web-guard support?
- The repository is archived and its Composer constraints likely predate the Laravel 10 and 11 and PHP 8.2+ era, so do not assume compatibility. Treat a clean install against your exact target framework version as a go/no-go spike rather than an assumption. Pin the Composer constraint to the Laravel minor you actually run and confirm the full dependency tree resolves. If it does not, you will need to patch constraints in a fork.
- Can I use this package for an API or SPA backend?
- No. This package is a session-based web guard for server-rendered Laravel apps, not a stateless token validator. API backends, mobile clients, and SPA-first architectures need a bearer-token validation guard, the sibling API-oriented package, or a backend-for-frontend pattern. Confirm your intended topology before treating this as a candidate at all, because the wrong shape here means rework rather than configuration.
- How does role-based route protection work with Keycloak roles?
- The guard exposes Keycloak roles so you can protect routes with middleware rather than writing custom authorization logic. Whether realm roles and client roles, and group claims, map cleanly onto Laravel gates and policies without forking is a key question to answer in your evaluation. In practice you will map Keycloak claims to gate checks or middleware in your app layer. Test the mapping against a real realm with representative users before committing.
- How are access and refresh tokens stored and refreshed by this guard?
- Tokens are persisted in the Laravel session, which is acceptable when the session driver is server-side (Redis or database) and not acceptable if tokens end up in cookies readable by JavaScript. The guard refreshes tokens and re-authenticates when refresh fails, but you should verify refresh-token rotation behavior and the exact re-auth path in your own environment. Treat token storage and refresh failure handling as explicit audit items, not assumptions.
- Does laravel-keycloak-web-guard support logout and clearing the Laravel session?
- Logout is part of the package's advertised scope, and it should invalidate the Laravel session alongside ending the Keycloak session. RP-initiated logout at the Keycloak end is worth verifying explicitly, since behavior depends on your client configuration and Keycloak version. Test the full flow: user clicks logout, Laravel session is cleared, and a subsequent protected route redirects back to Keycloak for a fresh login.
- Is laravel-keycloak-web-guard still maintained and safe for production?
- The repository is archived, and its score of roughly 4.95 out of 10 reflects that lifecycle risk rather than engineering failure. An archived package gets no CVE response, no OIDC spec corrections, and no dependency bumps while its transitive JWT, JOSE, and HTTP client libraries keep drifting. The realistic options are consuming it as-is with a pinned lockfile and documented risk acceptance, forking it into your own VCS namespace with compatibility patches, or reimplementing the guard in-house, which is only a few hundred lines. Forking is usually the default recommendation.
- How do I migrate from Socialite or a custom OIDC integration to this guard?
- From a bespoke OIDC or SAML integration, or from Socialite, this is largely a guard swap behind the same route middleware, which makes it comparatively clean. From local Laravel auth, run both guards during a transition period and link accounts on a stable claim such as sub, with email as a fallback plus a reconciliation job. Do not attempt a hard cutover, because user identity mapping is where these migrations fail. Retire the local guard only after the mapping is proven in production.
- What OIDC security details should I verify before trusting this guard?
- Confirm that state and nonce are validated on the callback and that the ID token signature is verified against Keycloak's keys. Check whether PKCE is supported, how refresh-token rotation is handled, and whether tokens live only in server-side session storage. Also confirm the package does not call the userinfo or introspection endpoint on every request, since that creates a hot-path dependency on Keycloak availability. These protocol-level checks matter more than the small amount of integration code.
Weaver
How can I help you explore Laravel packages today?