Keycloak SSO by Hatim El Oufir

Key Features
Getting Started
Installation
Project Board
- How to Use the Project Board
- Questions or Need Help?

Introduction
Key Features
Getting Started
Installation
Project Board
- How to Use the Project Board
- Questions or Need Help?

Filament Keycloak is a powerful authentication and authorization package that seamlessly integrates with Keycloak, enabling you to secure your applications and services with ease. This package simplifies the process of user authentication and fine-grained authorization, based on Keycloak roles and permissions.

#Key Features

Effortless Integration: Filament Keycloak offers a hassle-free integration process with Keycloak, a leading identity and access management platform.
User Authentication: Easily authenticate users with Keycloak's secure and industry-standard protocols, ensuring a seamless and reliable user experience.
Role-Based Authorization: Utilize Keycloak roles to implement fine-grained access control within your applications. Define who can perform specific actions or access certain resources with precision.
Customization: Tailor the authentication and authorization mechanisms to fit your application's unique requirements, providing flexibility and control.
Security: Leverage the robust security features of Keycloak to protect your application from unauthorized access and data breaches.
Documentation: Extensive documentation and examples make it easy to get started and integrate Filament Keycloak into your project.

#Getting Started

Install Filament Keycloak on your Laravel project.
Configure your environment with your Keycloak REALM and CLIENT.
Define roles and permissions in Keycloak to control access to your application's resources.
Implement role-based authorization logic in your application code, seamlessly leveraging Keycloak's features.
Enjoy a secure, user-friendly, and finely-tuned authentication and authorization system.

#Installation

GET THE PACKAGE

First of all thank you for purchasing Filament Keycloak!

Below you'll find extensive documentation on installing and using this plugin. Of course, if you have any questions, find a bug, need support, or have a feature request, please don't hesitate to reach out to me at eloufirhatim@gmail.com.

#Requirements

Filament Keycloak requires the following:

PHP 8.1+
Filament 3+
A database of your choice
Keycloak 22+ (will be tested in older version for compatibility)

#Installing with Composer

To install Filament Keycloak you'll need to add the package via repositories to your composer.json file:

{
    "repositories": [
         {
             "type": "composer",
             "url": "https://filament-keycloak-sso.composer.sh"
         }
    ]
}

Once the repository has been added to your composer.json file, you can install Filament Keycloak like any other composer package using the composer require command:

composer require heloufir/filament-keycloak-sso

Next, you will be prompted to provide your username and password.

Loading  composer  repositories  with  package  information
Authentication  required  (filament-keycloak-sso.composer.sh):
Username:  [license-email]
Password:  [license-key]

Here you need to type your email address (used to purchase the package) and for the password it will be your purchased package License Key.

#Configuration

Now that you have the package installed in your project, you need to follow the below steps to make it works:

Publish migrations: the package use a single table to store and manage Keycloak roles, so you need to execute the following commands:

php artisan vendor:publish --tag=filament-keycloak-sso-migrations
 
php artisan migrate

Publish configurations: the package use also a configuration file to manage Keycloak credentials and some logic, so if you want some customizations you can publish the configuration file using the following command:

php artisan vendor:publish --tag=filament-keycloak-sso-config

This will publish the following file config/filament-keycloak-sso.php.

To configure your Keycloak credentials, you need to define the following variables in your .env file:

KEYCLOAK_BASE_URL="Your keycloak base url, example: http://keycloak.domaine.com"
KEYCLOAK_REALM="Your keycloak realm"
KEYCLOAK_CLIENT_ID="Your keycloak client id"
KEYCLOAK_CLIENT_SECRET="Your keycloak client secret"

Publish translations: to customize the package translations you can publish it using the following command:

php artisan vendor:publish --tag=filament-keycloak-sso-translations

Enable plugin: to enable the plugin in your Filament application, you only need to add the following to your Panel provider:

// imports
use Heloufir\FilamentKeycloakSso\FilamentKeycloakSsoPlugin;
 
// panel method
public function panel(Panel $panel): Panel
{
    return $panel
        //...
        ->plugins([
            new FilamentKeycloakSsoPlugin()
        ]);
}

After you enabled the plugin login, registration, passwordReset, emailVerification and profile behaviour will change as follows:

login will now use the Heloufir\FilamentKeycloakSso\Pages\SsoLogin class provided by the package
profile will now use the Heloufir\FilamentKeycloakSso\Pages\SsoProfile class provided by the package
registration, passwordReset and emailVerification are disabled by the package, because it's managed by Keycloak now!

#Roles management

To manage the user roles you can use the trait provided by the package Heloufir\FilamentKeycloakSso\Helpers\HasKeycloakRoles as follows:

<?php
 
// imports
use Heloufir\FilamentKeycloakSso\Helpers\HasKeycloakRoles;
 
class User extends Authenticatable
{
    // other traits
    use HasKeycloakRoles;
 
    // ...
}

This trait will give your User modal the following methods:

roles(): array|null: this method will return an array of the users roles configured in Keycloak

Important: this roles are the ones configured inside the realm_access roles

// Example
$user = User::first();
 
$roles = $user->roles();
/*
    Results
    ['manage_user', 'manage_roles']
*/

hasAnyRoles(array $roles): bool: this method takes in parameter an array of roles, and returns true if any of the roles passed in parameters exists in the user roles list

// Example, based on the user roles list above
// ['manage_user', 'manage_roles']
 
$user->hasAnyRoles(['manage_user']); // true
 
$user->hasAnyRoles(['manage_user', 'manage_roles']); // true
 
$user->hasAnyRoles(['manage_user', 'not_existing_role']); // true
 
$user->hasAnyRoles(['not_existing_role']); // false

hasAllRoles(array $roles): bool: this method takes in parameter an array of roles, and returns true if all of the roles passed in parameters exists in the user roles list

// Example, based on the user roles list above
// ['manage_user', 'manage_roles']
 
$user->hasAllRoles(['manage_user']); // true
 
$user->hasAllRoles(['manage_user', 'manage_roles']); // true
 
$user->hasAllRoles(['manage_user', 'not_existing_role']); // false
 
$user->hasAllRoles(['not_existing_role']); // false

#Choose between Filament or Keycloak Auth

You can choose between Filament Login page or a redirection to Keycloak Login page to handle your users authentication, just by specifying an environment parameter into your .env file:

#Filament Login (default behaviour)

This is the default behaviour, or you can specify the following parameter in your .env file:

KEYCLOAK_EMBEDDED_AUTH=true

Here is the results:

#Keycloak redirection Login

You can specify the following parameter in your .env file:

KEYCLOAK_EMBEDDED_AUTH=false

Here is the results:

#Project Board

Our development progress, feature requests, and bug tracking are all transparently managed through our GitHub project board. This board provides you with insights into what's in the pipeline and what we're currently working on. It's also the place where you can suggest new features or report issues.

Project Board is accessible here: Filament Keycloak project board

#How to Use the Project Board

1. Explore Upcoming Features: Check out the "To Do" and "In Progress" columns to see what we have planned and what we're actively working on.

2. Report Issues: If you encounter any problems, bugs, or have feature requests, please send me an email to me at eloufirhatim@gmail.com.

3. Feature Requests: Have an idea for a new feature or improvement? Don't hesitate to reach out to me at eloufirhatim@gmail.com, and I will consider it for future development.

#Questions or Need Help?

If you have questions or need assistance, join the package discord server: https://discord.gg/6VTCbcNY