leandrose/laravel-keycloak-guard

A Laravel authentication guard for Keycloak OAuth2 resource servers with token introspection and optional caching support.

v1.0.0 2026-03-09 15:02 UTC

Requires

• php: ^8.2
• ext-json: *
• ext-openssl: *
• firebase/php-jwt: ^6.3|^7
• guzzlehttp/guzzle: ^6.5|^7
• illuminate/auth: ^10|^11|^12
• illuminate/cache: ^10|^11|^12
• illuminate/contracts: ^10|^11|^12
• illuminate/http: ^10|^11|^12
• illuminate/support: ^10|^11|^12

Requires (Dev)

• ext-pdo_sqlite: *
• orchestra/testbench: ^8|^9|^10
• phpunit/phpunit: ^9.5|^10

MIT

• leandrose

• Authentication
• oauth2
• laravel
• guard
• keycloak
• openid-connect
• resource-server
• bearer-token

README

A lightweight Laravel authentication guard for applications acting as OAuth2 / OpenID Connect resource servers using Keycloak.

This package validates Bearer tokens issued by Keycloak by first verifying the JWT signature locally with the realm public key and then confirming the token through the token introspection endpoint.

It also provides optional caching of introspection responses to reduce load on the Keycloak server and improve API performance.

Features

• Stateless Bearer Token authentication
• Keycloak OAuth2 / OpenID Connect integration
• Token validation via local JWT verification plus introspection endpoint
• Optional introspection caching
• Cache TTL automatically respecting token expiration (exp)
• Custom Laravel Guard
• Works with Laravel 10, 11 and 12

Requirements

• PHP 8.2+
• Laravel 10 / 11 / 12
• Keycloak server with OAuth2 / OpenID Connect enabled
• Keycloak realm public key available to the application

Version Compatibility

Package Version	Laravel 10	Laravel 11	Laravel 12
v1.0	✅	✅	✅

Installation

Install the package via Composer:

composer require leandrose/laravel-keycloak-guard

Publish the configuration file:

php artisan vendor:publish --provider="LeandroSe\\KeycloakGuard\\KeycloakAuthServiceProvider"

Add this to the guards array in config/auth.php:

'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],
'guards' => [
    'keycloak' => [
        'driver' => 'keycloak',
        'provider' => 'users',
    ],
],

Configure the Keycloak connection in your environment:

KEYCLOAK_BASE_URL=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_REALM_PUBLIC_KEY="..."

KEYCLOAK_REALM_PUBLIC_KEY can be provided either as a full PEM or as the raw base64 body of the public key.