Simple Keycloak Guard for Laravel / Lumen

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

Requirements

✔️ 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.

💔 If your app does not match requirements, probably you are looking for https://socialiteproviders.com/Keycloak

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

Install

Laravel / Lumen

Require the package

composer require robsontenorio/laravel-keycloak-guard

Lumen only

Register the provider in your boostrap app file

bootstrap/app.php

Add the following line in the "Register Service Providers" section at the bottom of the file.

$app->register(\KeycloakGuard\KeycloakGuardServiceProvider::class);

For facades, uncomment

$app->withFacades();

bootstrap/app.php

Configuration

Keycloak Guard

The Keycloak Guard configuration can be handled from Laravel

.env

Optionally you can publish the config file.

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

 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)
];

✔️ realmpublickey

Required.

The Keycloak Server realm public key (string).

How to get realm public key? Click on "Realm Settings" > "Keys" > "Algorithm RS256" Line > "Public Key" Button

✔️ loaduserfrom_database

Required. Default is

true

If you do not have an

users

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

user_provider_credential

token_principal_attribute

✔️ userprovidercredential

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

✔️ tokenprincipalattribute

Required. Default is

preferred_username

The property from JWT token that contains the user identifier. This will be confronted against

user_provider_credential

✔️ appenddecodedtoken

Default is

false

Appends to the authenticated user the full decoded JWT token (

$user->token

false

Auth::token()

✔️ allowed_resources

Required

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

Laravel Auth

Changes on

config/auth.php

php
...
'defaults' => [
        'guard' => 'api', # m building an API
        'passwords' => 'users',
    ],
....

'guards' => [
    'api' => [
        'driver' => 'keycloak', #  'users',
    ],
],

Laravel Routes
Just protect some endpoints on routes/api.php and you are done!
```php
// public endpoints
Route::get('/hello', function () {
    return ':)';
});
// protected endpoints
Route::group(['middleware' => 'auth:api'], function () {
    Route::get('/protected-endpoint', '[email protected]');
    // more endpoints ...
});

Lumen Routes

Just protect some endpoints on 
routes/web.php
 and you are done!
// public endpoints
$router->get('/hello', function () {
    return ':)';
});

// protected endpoints
$router->group(['middleware' => 'auth'], function () {
    $router->get('/protected-endpoint', '[email protected]');
    // more endpoints ...
});

API

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()

• 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-backend-role1',
        'myapp-backend-role2'
      ]
  ],
  'myapp-frontend' => [
    'roles' => [
      'myapp-frontend-role1',
      'myapp-frontend-role2'
    ]
  ]
]

Auth::hasRole('myapp-backend', 'myapp-backend-role1') // true
Auth::hasRole('myapp-frontend', 'myapp-frontend-role1') // true
Auth::hasRole('myapp-backend', 'myapp-frontend-role1') // false

Contact

Twitter @robsontenorio