- How do I install marchenkovma/laravel-keycloak in a Laravel app?
- Run composer require marchenkovma/laravel-keycloak, then publish the package configuration and any assets so you can set your Keycloak realm, client, and redirect values. The package targets PHP 8.4 or newer with the openssl extension enabled on a Laravel 13 host, so confirm that platform floor first. After publishing, keep the client secret in your environment file rather than in committed configuration.
- Which Laravel and PHP versions does laravel-keycloak support?
- The package requires PHP 8.4 or newer and Laravel 13, which acts as a hard floor rather than a soft recommendation. A host application still on Laravel 11 or 12 cannot adopt it without an override, so verify your version before scoping any work. If you need wider support, ask the maintainer whether the constraint could be relaxed to allow Laravel 12 alongside 13.
- How does the OpenID Connect authorization flow work with Keycloak?
- The package drives the OpenID Connect authorization flow against your Keycloak realm, redirecting the user to Keycloak and handling the callback that returns the authorization code and tokens. It then maps the Keycloak user, roles, and claims into Laravel so the framework auth system can work with them. Realm, client, and redirect settings come from the publishable configuration, so each environment can point at a different Keycloak instance.
- How do I protect Laravel routes with Keycloak guards and middleware?
- You register the package guard and apply its middleware to the routes or route groups that should sit behind Keycloak authentication, much like Laravel's built-in guards. Requests are then validated against Keycloak-issued access tokens, so unauthenticated or unauthorized traffic is rejected before it reaches your controllers. Role checks can be layered on top using the role information mapped from Keycloak.
- How are Keycloak roles and claims mapped to Laravel users?
- The package maps Keycloak users, roles, and claims into Laravel's user and authorization model, driven by the published configuration file. That lets you check Keycloak roles through normal Laravel authorization patterns instead of parsing tokens by hand. Because the mapping is configurable, review it per realm so client roles and realm roles land where your application actually expects them.
- Why is the package's Welcome page rendering inside my Inertia layout?
- Version 0.5.1 added a README note explaining this: when resources/js/app.ts registers a default layout for all pages, the package's Inertia Welcome page receives it too. Exclude the page by name in the layout resolver, for example layout: (name) => (name === 'Welcome' ? null : AppLayout). Setting layout: null inside the page component does not work, because Inertia re-applies the default layout.
- Is the Welcome page name part of the package's public contract?
- The documented workaround keys directly on the string Welcome, so renaming the page, or locale-switching page names in your app, silently stops the exception from matching and the layout bug returns without an error. The available notes do not state that the page name is a guaranteed contract, so treat it as fragile. Consider keying the exception on a route name, an exported constant, or a layout property, and raise that with the maintainer.
- Are the package's Inertia pages published into my application or served from vendor?
- The package ships auth-related frontend UI, specifically an Inertia page named Welcome, and setup involves publishing configuration and assets. The available notes do not definitively confirm whether that Inertia page is copied into your resources directory or served from the vendor folder, which matters because vendor files are overwritten on upgrade. Check the publish tags after installing so you know whether your layout workaround survives composer update.
- What does the openssl requirement mean for laravel-keycloak?
- The package declares an openssl dependency, which points to signing, token, or encryption work in the backend flow, although the notes do not spell out the exact algorithm or key management approach. A missing extension is a boot-time hard failure rather than a graceful degradation, so confirm it is enabled in your container image and CI matrix. Ask the maintainer about key management before going to production.
- Is version 0.5.1 safe to upgrade to, and is the package production ready?
- Release 0.5.1 changed documentation only, so upgrade regression risk is essentially zero. The behavior it documents already existed in earlier versions, so any integration built on 0.5.0 or below may have been rendering the login page inside an authenticated-style layout and should be audited rather than simply upgraded. The package remains 0.x with no API stability guarantee or stated deprecation policy, so pin versions and ask about the 1.0 roadmap before committing in production.