Upgrade guide¶
From 1.x to 2.0¶
2.0 is a rewrite, but the 1.x public API keeps working: config keys, routes, middleware aliases,
KCAuth, KCUserModel, and the KeycloakUsersService, KeycloakRoleService, KeycloakGroupService and
KeycloakJWTService classes.
composer require bhry98/keycloak-laravel-auth:^2.0
php artisan migrate # safe to run; nothing changes for existing 1.x tables
php artisan keycloak:check
Requirements¶
- PHP 8.2+ and Laravel 11, 12 or 13.
creativeorange/gravataris no longer required.avatar_urlbuilds the Gravatar URL itself. Remove the package if nothing else uses it.
Behaviour changes to review¶
| Area | 1.x | 2.0 | What to do |
|---|---|---|---|
keycloak.web |
introspection call to Keycloak on every request | local expiry check + silent refresh | Nothing. Set KEYCLOAK_WEB_VALIDATION=introspect to keep server-side checks (now cached). |
keycloak.api |
verified the token, $request->user() was empty |
also resolves the user (provisioned or stateless) | Set KEYCLOAK_PROVISIONING=false to keep APIs database-free. |
keycloak.api failure body |
{"error": "..."} |
same, plus message when APP_DEBUG=true |
none |
| Logout | redirected to Keycloak, user stayed there | RP-initiated logout, user returns to redirect_after_logout |
Add the URL to Valid post logout redirect URIs. |
| Login | no PKCE | PKCE (S256) | none (KEYCLOAK_PKCE=false to disable) |
| Invalid OAuth state | Cache::clear() (wiped the whole app cache!) |
restarts the login | none |
VerifyKeycloakTokenForAgent |
Auth::login() + session write per request |
sets the user for the request only | none |
KeycloakRoleService::guard('x') |
managed the admin realm | manages realm x (no guard() call → admin realm, as before) |
Check calls that relied on the bug. |
KeycloakGroupService::createGroup() |
crashed (dd()) |
returns true |
none |
| Admin token | cached 55 seconds | cached for its real lifetime, refreshed on 401 | none |
| Users migration | failed when users already existed |
adds the missing columns | none |
Users migration down() |
dropped users |
no-op (never drops your users table) | none |
Recommended (optional) changes¶
// Before
$jwt = (new KeycloakJWTService)->validateAndDecode($token);
$roles = KCAuth::userRoles();
(new KeycloakRoleService)->assignRoleToUser($userId, 'editor');
// After
$token = Keycloak::check($token, 'api');
$roles = Keycloak::token()->roles();
Keycloak::users()->assignRealmRoles($userId, ['editor']);
- Use the
keycloakauth guard for APIs. - Replace
VerifyKeycloakTokenForAgent/VerifyKeycloakTokenForApiAgentwithkeycloak.api. - Replace hand-written
Http::withToken(...)service calls withHttp::withKeycloakToken(). - Use
actingAsKeycloakUser()in your tests.
Changelog¶
2.0.0¶
Added
Keycloakfacade /KeycloakManageras the single entry point.keycloakauth-guard driver; statelessKeycloakUser;HasKeycloakRolestrait.- Offline JWT verification with cached JWKS, key-rotation handling, issuer / audience / type / algorithm checks.
keycloak.role,keycloak.roles,keycloak.scope,keycloak.permissionmiddleware; gates; Blade directives.- OIDC client: password, refresh, client credentials, code, token exchange, introspection, userinfo, logout, revoke, discovery, UMA permissions.
- Cached service tokens,
Http::withKeycloakToken()andHttp::withKeycloakUserToken(). - Admin API: users, realm roles, groups, clients and client roles, realm events, lazy pagination.
keycloak:install,keycloak:check,keycloak:decode,keycloak:clear-cache.- Events, testing helpers, PKCE, configurable routes / cache / HTTP, Laravel 11–13 support, CI.
Fixed
- Leftover
dd()calls in the role and group services. - Missing
firebase/php-jwtrequirement. - Wrong certificates URL in
VerifyKeycloakTokenForApiAgent. Cache::clear()on invalid OAuth state.- Role service targeting the wrong realm.
- Session fixation after login.
1.0.0¶
First release: Socialite login, keycloak.web / keycloak.api middleware, users / roles / groups services.