Skip to content
πŸ”‘ Simple Keycloak Guard for Laravel
Branch: master
Clone or download
robsontenorio Merge pull request #9 from cunio-martin/patch-1
Proper handling of token without resource_access
Latest commit 310d628 May 2, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Allows authentication without "users" table. Feb 4, 2019
src Proper handling of token without resource_access Apr 26, 2019
tests Fix tests for phpunit 8 compatibility May 2, 2019
.gitignore Allows authentication without "users" table. Feb 4, 2019
.travis.yml Allows authentication without "users" table. Feb 4, 2019
phpunit.xml.dist Testings Jul 24, 2018


Simple Keycloak Guard for Laravel

This package helps you authenticate users on a Laravel API based on JWT tokens generated from Keycloak Server.


βœ”οΈ I`m building an API with Laravel.

βœ”οΈ I will not use Laravel Passport for authentication, because Keycloak Server will do the job.

βœ”οΈ The frontend is a separated project.

βœ”οΈ The frontend users authenticate directly on Keycloak Server to obtain a JWT token. This process have nothing to do with the Laravel API.

βœ”οΈ The frontend keep the JWT token from Keycloak Server.

βœ”οΈ The frontend make requests to the Laravel API, with that token.

The flow

  1. The frontend user authenticates on Keycloak Server

  2. The frontend user obtains a JWT token.

  3. In another moment, the frontend user makes a request to some protected endpoint on a Laravel API, with that token.

  4. The Laravel API (through Keycloak Guard) handle it.

    • Verify token signature.
    • Verify token structure.
    • Verify token expiration time.
    • Verify if my API allows resource access from token.
  5. If everything is ok, find the user on database and authenticate it on my API.

  6. Return response


Require the package

composer require robsontenorio/laravel-keycloak-guard

Publish the config file

php artisan vendor:publish  --provider="KeycloakGuard\KeycloakGuardServiceProvider"


Keycloak Guard

The Keycloak Guard configuration can be handled from Laravel .env file. ⚠️ Be sure all strings are trimmed.


return [  
  'realm_public_key' => env('KEYCLOAK_REALM_PUBLIC_KEY', null),

  'load_user_from_database' => env('KEYCLOAK_LOAD_USER_FROM_DATABASE', true),

  'user_provider_credential' => env('KEYCLOAK_USER_PROVIDER_CREDENTIAL', 'username'),

  'token_principal_attribute' => env('KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE', 'preferred_username'),

  'append_decoded_token' => env('KEYCLOAK_APPEND_DECODED_TOKEN', false),

  'allowed_resources' => env('KEYCLOAK_ALLOWED_RESOURCES', null)

βœ”οΈ realm_public_key


The Keycloak Server realm public key (string).

βœ”οΈ load_user_from_database

Required. Default is true.

If you do not have an users table you must disable this.

It fetchs user from database and fill values into authenticated user object. If enabled, it will work together with user_provider_credential and user_provider_credential.

βœ”οΈ user_provider_credential

Required. Default is username.

The field from "users" table that contains the user unique identifier (eg. username, email, nickname). This will be confronted against token_principal_attribute attribute, while authenticating.

βœ”οΈ token_principal_attribute

Required. Default is preferred_username.

The property from JWT token that contains the user identifier. This will be confronted against user_provider_credential attribute, while authenticating.

βœ”οΈ append_decoded_token

Default is false.

Appends to the authenticated user the full decoded JWT token. Useful if you need to know roles, groups and another user info holded by JWT token. Even choosing false, you can also get it using Auth::token(), see API section.

βœ”οΈ allowed_resources


Usually you API should handle one resource_access. But, if you handle multiples, just use a comma separated list of allowed resources accepted by API. This attribute will be confronted against resource_access attribute from JWT token, while authenticating.

Laravel Auth

Changes on config/auth.php

'defaults' => [
        'guard' => 'api', # <-- For sure, i`m building an API
        'passwords' => 'users',

    'guards' => [
        'api' => [
            'driver' => 'keycloak', # <-- Set the API guard driver to "keycloak"
            'provider' => 'users',

Laravel Routes

Just protect some endpoints on routes/api.php and you are done!

// public endpoints
Route::get('/hello', function () {
    return ':)';

// protected endpoints
Route::group(['middleware' => 'auth:api'], function () {
    Route::get('/protected-endpoint', 'SecretController@index');
    // more endpoints ...


Simple Keycloak Guard implements Illuminate\Contracts\Auth\Guard. So, all Laravel default methods will be available. Ex: Auth::user() returns the authenticated user.

Default methods:

  • check()
  • guest()
  • user()
  • id()
  • validate()
  • setUser()

Keycloak Guard methods:

  • token()

Ex: Auth::token() returns full decoded JWT token from authenticated user

  • hasRole('some-resource', 'some-role'): Check if the authenticated user has especific role into a resource.

Ex: Whit this payload:

'resource_access' => [
  'myapp-backend' => [
      'roles' => [
  'myapp-frontend' => [
    'roles' => [
Auth::hasRole('myapp-backend', 'myapp-backend-role1') => true
Auth::hasRole('myapp-frontend', 'myapp-frontend-role1') => true
Auth::hasRole('myapp-backend', 'myapp-frontend-role1') => false


Twitter @robsontenorio

You can’t perform that action at this time.