Download the PHP package febrianrz/laravel-keycloak-guard without Composer
On this page you can find all versions of the php package febrianrz/laravel-keycloak-guard. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download febrianrz/laravel-keycloak-guard
More information about febrianrz/laravel-keycloak-guard
Files in febrianrz/laravel-keycloak-guard
Package laravel-keycloak-guard
Short Description 🔑 Simple Keycloak Guard for Laravel
License MIT
Homepage https://github.com/robsontenorio/laravel-keycloak-guard
Informations about the package laravel-keycloak-guard
Simple Keycloak Guard for Laravel
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 or https://github.com/Vizir/laravel-keycloak-web-guard
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 access
from token.
-
If everything is ok, then find the user on database and authenticate it on my API.
-
Optionally, the user can be created / updated in the API users database.
- Return response
Install
Laravel / Lumen
Require the package
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.
For facades, uncomment $app->withFacades();
in your boostrap app file bootstrap/app.php
Configuration
Keycloak Guard
⚠️ When editing .env
make sure all strings are trimmed.
✔️ realm_public_key
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
✔️ 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 token_principal_attribute
.
✔️ user_provider_custom_retrieve_method
Default is null
.
If you have an users
table and want it to be updated (creating or updating users) based on the token, you can inform a custom method on a custom UserProvider, that will be called instead retrieveByCredentials
and will receive the complete decoded token as parameter, not just the credentials (as default).
This will allow you to customize the way you want to interact with your database, before matching and delivering the authenticated user object, having all the information contained in the (valid) access token available. To read more about custom UserProviders, please check Laravel's documentation about.
If using this feature, obviously, values defined for user_provider_credential
and token_principal_attribute
will be ignored.
✔️ 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 ($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 _resourceaccess. 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.
✔️ ignore_resources_validation
Default is false
.
Disables entirely resources validation. It will ignore _allowedresources configuration.
✔️ leeway
Default is 0
.
You can add a leeway to account for when there is a clock skew times between the signing and verifying servers. If you are facing issues like "Cannot handle token prior to 60
(seconds).
✔️ input_key
Default is null
.
By default this package always will look at first for a Bearer
token. Additionally, if this option is enabled, then it will try to get a token from this custom request param.
Laravel Auth
Changes on config/auth.php
Laravel Routes
Just protect some endpoints on routes/api.php
and you are done!
Lumen Routes
Just protect some endpoints on routes/web.php
and you are done!
API
Simple Keycloak Guard implements Illuminate\Contracts\Auth\Guard
. So, all Laravel default methods will be available.
Default Laravel methods
check()
guest()
user()
id()
validate()
setUser()
Keycloak Guard methods
Token
token()
Returns full decoded JWT token from authenticated user.
Role
hasRole('some-resource', 'some-role')
_Check if authenticated user has a role on resourceaccess
hasAnyRole('some-resource', ['some-role1', 'some-role2'])
_Check if the authenticated user has any of the roles in resourceaccess
Scope
Example decoded payload:
scopes()
Get all user scopes
hasScope('some-scope')
Check if authenticated user has a scope
hasAnyScope(['scope-a', 'scope-c'])
Check if the authenticated user has any of the scopes
Acting as a Keycloak user in tests
As an equivelant feature like $this->actingAs($user)
in Laravel, with this package you can use KeycloakGuard\ActingAsKeycloakUser
trait in your test class and then use actingAsKeycloakUser()
method to act as a user and somehow skip the Keycloak auth:
If you are not using keycloak.load_user_from_database
option, set keycloak.preferred_username
with a valid preferred_username
for tests.
Contribute
You can run this project on VSCODE with Remote Container. Make sure you will use internal VSCODE terminal (inside running container).
Contact
Twitter @robsontenorio