Skip to content

Installation

Requirements

PHP 8.2 or newer, with ext-openssl and ext-json
Laravel 11.x, 12.x or 13.x
Keycloak 17 or newer (URLs without /auth). For older servers, put /auth in KEYCLOAK_BASE_URL.

Install via Composer

composer require bhry98/keycloak-laravel-auth

The service provider and the Keycloak facade are auto-discovered.

php artisan keycloak:install      # publishes config/bhry98-keycloak.php and prints the .env keys
php artisan migrate               # adds the Keycloak columns to your users table

Users table

The bundled migration creates a users table, or, if your app already has one (Laravel's default migration), adds the Keycloak columns (keycloak_id, keycloak_realm, username, ...) and makes password nullable. To customise it, set migrations.auto_load to false and publish it: php artisan vendor:publish --tag=bhry98-keycloak-migrations.

You only need the table if you use the browser login or user provisioning. A pure API that uses stateless users needs no table at all.

Environment

The minimum for one realm and one client:

KEYCLOAK_BASE_URL=https://sso.example.com
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=my-laravel-app
KEYCLOAK_CLIENT_SECRET=change-me
KEYCLOAK_REDIRECT_URI="${APP_URL}/auth/keycloak/callback/web"

Every guard (web, api, admin) falls back to these values. Override them per guard when you use different clients:

# Browser login client
KC_WEB_CLIENT_ID=my-web-app
KC_WEB_CLIENT_SECRET=...

# API resource server: tokens must be issued for this audience
KC_API_CLIENT_ID=orders-api
KC_API_AUDIENCE=orders-api

# Admin REST API service account (can live in another realm)
KC_ADMIN_REALM=my-realm
KC_ADMIN_CLIENT_ID=laravel-admin
KC_ADMIN_CLIENT_SECRET=...

Then check everything is reachable:

php artisan keycloak:check --admin
+-------+----------+----------------+------------------------------------------+-------------------+--------------------+
| Guard | Realm    | Client         | Discovery                                | JWKS              | Client credentials |
+-------+----------+----------------+------------------------------------------+-------------------+--------------------+
| web   | my-realm | my-web-app     | https://sso.example.com/realms/my-realm  | 1 signing key(s)  | ok                 |
| api   | my-realm | orders-api     | https://sso.example.com/realms/my-realm  | 1 signing key(s)  | ok                 |
| admin | my-realm | laravel-admin  | https://sso.example.com/realms/my-realm  | 1 signing key(s)  | ok                 |
+-------+----------+----------------+------------------------------------------+-------------------+--------------------+
Admin API token: ok

Setting up Keycloak

Create the clients in your realm (Clients → Create client, type OpenID Connect).

Setting Value
Client authentication On (confidential)
Standard flow On
Valid redirect URIs https://your-app.test/auth/keycloak/callback/web
Valid post logout redirect URIs https://your-app.test/* (or +)
Web origins https://your-app.test
Advanced → PKCE method S256 (optional, the package always sends it)

The API only verifies tokens, so it needs no flow enabled. To require that tokens are meant for your API, add an Audience mapper to the client that issues the tokens (your SPA / mobile app):

  1. Client scopes → Create orders-api-audience → Mappers → By configuration → Audience, included client audience: orders-api.
  2. Add the scope to the SPA client as a Default scope.
  3. Set KC_API_AUDIENCE=orders-api.

Enable Service accounts on this client if it also calls other services with Http::withKeycloakToken().

Setting Value
Client authentication On
Standard flow Off
Service accounts roles On

Then in Service account roles → Assign role → Filter by clients, add the realm-management roles you need, for example manage-users, view-users, query-groups, view-clients or manage-realm.

For Keycloak::oidc()->password(), enable Direct access grants on the client. Prefer the browser flow for user-facing apps. The password grant is mainly useful for first-party mobile apps, CLIs and tests.

Roles, groups and scopes in the token

Keycloak puts realm roles in realm_access.roles and client roles in resource_access.<client>.roles by default (the roles client scope). For groups, add a Group Membership mapper (token claim name groups, Full group path on) to a client scope. See Authorization.

Next