- How do I install overtrue/laravel-keycloak-guard?
- Install the package with Composer using composer require overtrue/laravel-keycloak-guard. Laravel package auto-discovery should register the service provider, but check the README for any manual registration steps for your version. Publish the package configuration if instructed, then add your Keycloak realm and validation settings before enabling the guard.
- How does this package authenticate users with Keycloak?
- The package provides a custom Laravel guard that reads Keycloak-issued JWTs from incoming requests. It validates the token and resolves the identity from the token claims so Laravel's auth system can use it. You then protect routes with standard Laravel auth middleware rather than writing custom token parsing logic.
- Which Laravel versions are supported by overtrue/laravel-keycloak-guard?
- Supported Laravel versions depend on the specific package release, so check the composer.json constraints on Packagist or GitHub before installing. The package integrates with Laravel's guard and auth middleware system, but older framework versions may not be covered by newer releases. Pin a compatible package version in production and review upgrade notes when changing Laravel versions.
- How do I protect routes with Keycloak authentication in Laravel?
- Configure a guard entry in config/auth.php that uses the Keycloak guard driver provided by this package. Then apply Laravel's auth middleware to the routes or route groups you want to protect, referencing that guard if needed. Requests without a valid Keycloak JWT should be rejected by the guard before reaching your controller.
- Do I need to create local user records for Keycloak users?
- The guard resolves identities from validated Keycloak JWT claims, so many applications can authenticate API requests without creating local user rows first. If your app needs Eloquent users for relationships, roles, or audits, add your own mapping or synchronization from Keycloak claims to your users table. Keep that mapping explicit so authorization logic remains predictable.
- How is Keycloak realm or public key configuration handled?
- After publishing the package config, set the Keycloak realm, client, and token validation details as described in the README. The guard needs enough information to verify the JWT signature and issuer, such as realm public keys or a certificates endpoint. Avoid hard-coding secrets in source control and use environment variables for deployment-specific values.
- Can I use Laravel gates, policies, and auth helpers with this guard?
- Yes, once the guard resolves an authenticated identity, standard Laravel auth helpers and middleware can use it. Gates and policies can work if the resolved user object implements the contracts and attributes your authorization logic expects. Test the resolved identity shape carefully because it may come from JWT claims rather than an Eloquent model.
- How should I test routes protected by laravel-keycloak-guard?
- Write feature tests that send requests with valid, expired, and malformed JWTs and assert the expected 401 or 403 responses. Mock the guard or generate test tokens instead of calling a live Keycloak server in every test. Also test that authenticated requests reach your controllers and that authorization rules behave correctly for different claim sets.
- What happens with expired, refreshed, or revoked Keycloak tokens?
- The guard validates JWTs, so expired tokens should be rejected according to the token's claims and your validation configuration. Refresh flows are typically handled by your client or Keycloak itself, which obtains a new access token. Revocation may not be instantly visible with local JWT validation, so use Keycloak introspection or short token lifetimes if immediate revocation is required.
- When should I use this package instead of Laravel Sanctum or Passport?
- Use this package when Keycloak is your identity provider and Laravel needs to accept Keycloak-issued JWTs on protected routes. Sanctum is usually a better fit for first-party SPA or simple API token authentication, while Passport is an OAuth2 server for Laravel. This guard is focused on validating external Keycloak tokens rather than issuing tokens from your Laravel app.