- How do I install stevenmaguire/oauth2-keycloak in a Laravel project?
- Run `composer require stevenmaguire/oauth2-keycloak` in your project directory. The package extends the PHP League’s OAuth2 client, so no additional Laravel-specific dependencies are required beyond the base package.
- Which Laravel versions does this package support?
- The package is compatible with Laravel 8.x and 9.x, as it relies on the PHP League’s OAuth2 client, which has no Laravel-specific version constraints. Ensure your PHP version (8.0+) aligns with Keycloak’s requirements.
- Can I use this package for client credentials flow (e.g., API-to-API auth)?
- Yes, the package supports all OAuth2 flows, including client credentials. Configure the provider with your client ID, secret, and realm, then use `$provider->getAccessToken('client_credentials')` to fetch tokens for service-to-service communication.
- How do I handle Keycloak’s custom claims (e.g., groups, roles) in Laravel?
- After fetching the user profile with `$provider->getResourceOwner()`, manually map Keycloak claims (e.g., `groups` or `resource_access`) to your Laravel user model. Use Laravel’s `User` model observers or accessors to store and retrieve these claims dynamically.
- Does this package support PKCE for public clients (e.g., SPAs)?
- Yes, the package leverages the underlying league/oauth2-client, which includes PKCE support. Enable it by omitting the `clientSecret` in your provider configuration, forcing the use of PKCE for enhanced security.
- How do I integrate this with Laravel’s authentication system (e.g., guards)?
- Extend Laravel’s auth guards by creating a custom `KeycloakGuard` that uses the provider to validate tokens. Bind it in `config/auth.php` under `guards` and handle user retrieval in a `UserProvider` implementation.
- What if Keycloak is down? Can I fallback to local auth?
- The package itself doesn’t include fallback logic, but you can wrap provider calls in try-catch blocks and redirect users to Laravel’s default auth (e.g., `auth()->guard('web')->attempt()`) if Keycloak requests fail.
- Are there performance concerns with token introspection or validation?
- Token validation can be rate-limited by Keycloak. Cache introspection results in Redis or your preferred cache driver using Laravel’s cache facade to reduce calls. Avoid validating tokens on every request if possible.
- How do I configure Keycloak’s encryption (e.g., RS256) for token signing?
- Pass the `encryptionAlgorithm` (e.g., `'RS256'`) and `encryptionKeyPath` (path to your public key) or `encryptionKey` (key contents) to the provider constructor. This ensures tokens are validated against Keycloak’s public key.
- What alternatives exist for Keycloak OAuth2 in Laravel, and why choose this package?
- Alternatives include `socialiteproviders/keycloak` (for Socialite integration) or rolling your own with `league/oauth2-client`. This package offers Keycloak-specific optimizations (e.g., realm handling, token parsing) and tighter Laravel integration without Socialite’s overhead.