🔑 Simple Keycloak Guard for Laravel / Lumen
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.
💔 If your app does not match requirements, probably you are looking for https://socialiteproviders.com/Keycloak
The frontend user authenticates on Keycloak Server
The frontend user obtains a JWT token.
In another moment, the frontend user makes a request to some protected endpoint on a Laravel API, with that token.
The Laravel API (through
Keycloak Guard) handle it.
resource accessfrom token.
If everything is ok, find the user on database and authenticate it on my API.
Return response
Require the package
composer require robsontenorio/laravel-keycloak-guard
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();in your boostrap app file
bootstrap/app.php
The Keycloak Guard configuration can be handled from Laravel
.envfile. ⚠️ Be sure all strings are trimmed.
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
userstable 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_credentialand
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_attributeattribute, while authenticating.
✔️ tokenprincipalattribute
Required. Default is
preferred_username.
The property from JWT token that contains the user identifier. This will be confronted against
user_provider_credentialattribute, while authenticating.
✔️ appenddecodedtoken
Default is
false.
Appends to the authenticated user the full decoded JWT token (
$user->token). Useful if you need to know roles, groups and other user info holded by JWT token. Even choosing
false, you can also get it using
Auth::token(), see API section.
✔️ 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_accessattribute from JWT token, while authenticating.
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.phpand 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:
Ex:
Auth::token()returns full decoded JWT token from authenticated user
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
Twitter @robsontenorio