README

• Overview
• Features
• Keycloak Configurations
• Installation
• Configuration
• Integration
• Testing

Overview

LaraKeycloak provides Authentication using KeyCloak Socialite Provider and RBAC Authorization by checking user roles from Keycloak.

Features

• Provides Authentication using KeyCloak Socialite Provider
• Provides Authorization by RBAC managed by KeyCloak

Keycloak Configurations

Before installing LaraKeycloak, configure your Keycloak Server to add your application as Client.

Creating a Keycloak Client

Add User Roles in Keycloak Client

Create Users and Assign Roles

Create at least a Regular User and an Admin User, for testing Authorization later on.

Installation

composer require peppertech/larakeycloak

Configuration

Environment Variables

Variable	Required	Description	Default Value
KEYCLOAK_BASE_URL	Yes	Keycloak Server URL. ie. https://[keycloak server]/auth	none
KEYCLOAK_REALMS	Yes	Keycloak Realm	none
KEYCLOAK_CLIENT_ID	Yes	Keycloak Client ID	none
KEYCLOAK_CLIENT_SECRET	Yes	OpenId Connect Client Secret	none
KEYCLOAK_REDIRECT_URI	Yes	The default page to redirect users after login	/home
KEYCLOAK_REALM_PUBLIC_KEY	Yes	Keycloak Realm RS256 Public Key	none

Integration

Published Files

Run the following commands to publish the files to your app.

php artisan vendor:publish --tag="larakeycloak"

This will copy the following files:

• app/Http/Controllers/LaraKeyController.php, controller for the /auth/redirect and '/auth/callback` routes.
• app/Policies/SampleAdminPolicy.php, an example Admin Policy to secure certain pages in your application for admin role
• resources/views/sample_admin_blade.php, example Admin View with /sample/admin route.
• app/Http/Controllers/SampleAdminController.php, controller for the /sample/admin route.

Routes

Create the following routes in your app/routes/web.php

Route::group(['middleware' => ['auth:web']], function () {
    ...
    Route::get('/sample/admin', 'SampleAdminController@index')->name('sample-admin');
});

Route::get('/auth/redirect', 'LaraKeycloakController@redirect')->name('auth-redirect');
Route::get('/auth/callback', 'LaraKeycloakController@callback')->name('auth-callback');

Route::get('logout', '\App\Http\Controllers\Auth\LoginController@logout');

Add the following logout method in your LoginController

use Illuminate\Support\Facades\Auth;
use PepperTech\LaraKeycloak\LaraKeycloak;

....
public function logout()
{
    $larakc = new LaraKeyCloak();
    $larakc->logout();
    Auth::guard('web')->logout();
    return redirect()->guest(route('main'));   // `main` is the route name of public homepage
}

Socialite Keycloak Settings

Reference: https://socialiteproviders.com/Keycloak/#installation-basic-usage

• Add the following block in your config/services.php

'keycloak' => [    
        'client_id' => env('KEYCLOAK_CLIENT_ID'),  
        'client_secret' => env('KEYCLOAK_CLIENT_SECRET'),  
        'redirect' => env('KEYCLOAK_REDIRECT_URI'),
        'base_url' => env('KEYCLOAK_BASE_URL'),
        'realms' => env('KEYCLOAK_REALMS'),
        'realm_public_key' => env('KEYCLOAK_REALM_PUBLIC_KEY'),
    ],

• In app/Providers/EventServiceProvider.php, add the following:

use SocialiteProviders\Manager\SocialiteWasCalled;

protected $listen = [
        ....
        SocialiteWasCalled::class => [
            // add your listeners (aka providers) here
            'SocialiteProviders\\Keycloak\\KeycloakExtendSocialite@handle',
        ],
    ];

• In config/app.php add the SocialiteProviders\Manager\ServiceProvider::class and comment-out Laravel\Socialite\SocialiteServiceProvider::class if you have added this before.

'providers' => [
    ...
    // Laravel\Socialite\SocialiteServiceProvider::class,   
    SocialiteProviders\Manager\ServiceProvider::class,
]

Auth Middleware

• In app/Http/Middleware/Authenticate.php, change the redirectTo method. This change will make the redirection to Keycloak Login when an unauthenticated user access a protect part of the website.

protected function redirectTo($request)
{
    if (! Auth::check()) {
        return route('auth-redirect');
    }   
}

Authorization

Authorization is provided by roles of user from Keycloak. PepperTech\LaraKeycloak\LaraKeycloak class has a public method hasRole that checks if currently logged-in user has that role. hasRole can be used with Laravel Authorization

Defining Gates

• Define your Gate in app/Providers/AuthServiceProvider.php boot method

public function boot()
    {
        $this->registerPolicies();

        Gate::define('view-admin', [SampleAdminPolicy::class, 'view']);
        // define more Gates here
    }

Policies

• An example Policy is provided in app/Policies/SampleAdminPolicy.php that uses the LaraKeycloak hasRole method.
• An example Admin View Controller is also provided at app/Htttp/Controllers/SampleAdminController.php. Inspect how Gates are used here to check the user's authorization in viewing a page.

Testing

• To test if everything is working, navigate to http://[your domain]/sample/admin. This should redirct to Keycloak Login Page.
• Login with a Keycloak User that has 'admin' role.
• Upon login, you should be able to see the Sample Admin Page.
• Logout and go to http://[your domain]/sample/admin again. This time, login with a user that does not have an admin role.
• Upon login, you should see a 403 Unauthorized Page.