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
The flow
-
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.- Verify token signature.
- Verify token structure.
- Verify token expiration time.
- Verify if my API allows
resource accessfrom token.
-
If everything is ok, find the user on database and authenticate it on my API.
-
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(); in your boostrap app file bootstrap/app.php
Configuration
Keycloak Guard
The Keycloak Guard configuration can be handled from Laravel .env file.
Optionally you can publish the config file.
php artisan vendor:publish --provider="KeycloakGuard\KeycloakGuardServiceProvider"
<?php
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)
];
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
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 token_principal_attribute.
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.
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.
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.
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 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 ...
});
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', 'SecretController@index');
// 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() 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-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
![[Keycloak Guard] Algorithm not allowed](https://avatars.githubusercontent.com/u/19515622?v=4)
![[Keycloak error] Wrong number of segements](https://avatars.githubusercontent.com/u/13661520?v=4)
![Route [login] not defined.](https://avatars.githubusercontent.com/u/23563913?v=4)
40 Nov 11, 2022
7 Feb 21, 2022
2.4k Jan 6, 2023
10.7k Dec 31, 2022
651 Dec 1, 2022
141 Dec 21, 2022
490 Dec 27, 2022
578 Nov 30, 2022
1 Oct 12, 2021
10 Dec 14, 2021
34 Nov 21, 2022
374 Dec 21, 2022
26 Jun 20, 2021
689 Dec 25, 2022
2.4k Dec 30, 2022
1 Feb 9, 2022
1 Feb 4, 2022