Filament Keycloak Admin Laravel Package

Getting Started

1. Install the package with Composer and publish its config/views:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   php artisan vendor:publish --tag=<package>-views
   

2. Start with config/<package>.php (or config/keycloak.php) and the package service provider. These define the guard, Keycloak connection details, route middleware, and the new v1.2.0 extension points for audit and HTTP trace logging.
3. Set the minimum environment variables: Keycloak base URL, realm, client ID, client secret, and the callback/redirect URI. Register the guard and middleware in config/auth.php and bootstrap/app.php (or Kernel.php on older Laravel versions).
4. First use case: protect a small route group and perform a single SSO login round-trip.

   Route::middleware(['web', '<package>-auth'])->group(function () {
       Route::get('/dashboard', DashboardController::class);
   });
   

5. Verify the login redirect, callback handling, local user provisioning, and logout flow before adding audit logging. Then implement the audit extension point so you can see what the package is doing during development.

Implementation Patterns

• Guard and middleware integration: Use the package guard for web routes and apply its middleware to route groups. Keep public routes (login, callback, logout, error pages) outside the protected group.
• SSO login/callback flow: Let the package handle the redirect to Keycloak and the callback token exchange. In the callback, rely on the package’s user resolution/provisioning, then attach application-specific attributes (tenant, roles, team) in a listener or by extending the user provider.
• Role and claim mapping: Map Keycloak realm/client roles to Laravel gates and policies. Prefer a small mapping service or config map rather than scattering role checks through controllers.
• Audit logging extension point: v1.2.0 adds an extension point for audit logging. Bind your implementation (interface or event listener, depending on the package’s contract) in a service provider. Record login success/failure, logout, token refresh failures, user provisioning, and role changes. Keep audit writes asynchronous or queued where possible.
• HTTP trace logging extension point: Use the new trace hook to capture Keycloak HTTP calls during development and incident triage. Implement it as a listener or decorator that records method, URL, status, duration, and correlation ID. Redact authorization codes, tokens, secrets, and personal data before persisting.
• Error UI messages: v1.2.0 adds user-facing error messages for SSO auth errors and Keycloak HTTP API errors. Publish and override the views/blade components to match your application’s look and feel. Differentiate between retryable errors (Keycloak temporarily unavailable) and terminal errors (invalid client, expired session).
• Logout and session invalidation: Implement both local logout and Keycloak single sign-out where required. Confirm whether the package handles the end-session endpoint or whether you need to redirect to Keycloak’s logout URL yourself.
• Testing workflow: Use an in-memory or fake Keycloak provider for feature tests. Assert redirects, callback handling, guard behaviour, and the new error views. Add a test around each bound audit/trace extension so failures in those hooks do not break authentication.

Gotchas and Tips

• Redirect URI mismatch: The callback URL configured in Keycloak must match the application’s generated URL exactly, including scheme, host, port, and trailing slash. This is the most common cause of invalid_redirect_uri errors.
• Config and route caching: After changing guard, middleware, or extension-point bindings, clear caches with php artisan config:clear and php artisan route:clear. Extension bindings registered conditionally can behave differently once config is cached.
• Extension point timing: Bind audit and trace implementations in a service provider that runs before the package resolves its services. If your binding is ignored, check provider order and whether the package uses deferred providers.
• Sensitive data in traces: HTTP trace logging can accidentally capture bearer tokens, authorization codes, cookies, and Keycloak error bodies. Redact by default and opt in to payload logging only in non-production environments.
• Audit log volume: Authentication audit events can be high-volume. Queue writes, cap retention, and avoid writing synchronous database records on the login hot path.
• Error UI customisation: The new error messages are a starting point, not a complete UX. Publish the views early and review the wording for SSO and Keycloak HTTP API failures. Avoid leaking internal Keycloak URLs or raw API responses to end users.
• Token expiry and clock skew: Keycloak token lifetimes may be short. Ensure refresh handling works, and allow a small clock-skew leeway if you validate tokens locally.
• Debugging SSO failures: Enable the new HTTP trace extension point in staging, correlate with Keycloak server logs, and check the callback session state. Most failures are redirect URI, client secret, realm name, or stale session/cookie issues.
• Logout edge cases: Local logout does not necessarily end the Keycloak SSO session. Test back-button behaviour and single sign-out explicitly if your application requires it.
• Upgrade note for v1.2.0: The release is additive, but review published views and any service provider bindings after upgrading. If you already have custom audit or trace logging, move it behind the new extension points rather than duplicating package behaviour.