PHPackages                             tesda/keycloak-auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. tesda/keycloak-auth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

tesda/keycloak-auth
===================

Keycloak SSO OpenID Connect integration for Laravel applications.

v1.1.0(3w ago)02MITPHPPHP ^8.2

Since Jun 11Pushed 3w agoCompare

[ Source](https://github.com/Nyanta2598/keycloak-auth)[ Packagist](https://packagist.org/packages/tesda/keycloak-auth)[ RSS](/packages/tesda-keycloak-auth/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (5)Versions (3)Used By (0)

Keycloak SSO Auth Package (`tesda/keycloak-auth`)
=================================================

[](#keycloak-sso-auth-package-tesdakeycloak-auth)

A reusable Laravel package wrapping Socialite and the Keycloak provider to enable quick, standard OpenID Connect (OIDC) Single Sign-On (SSO) integration with Keycloak (such as `sso-tesda`).

Features
--------

[](#features)

- **Zero-Config Socialite Binding:** Automatically registers the Keycloak Socialite provider.
- **Pre-configured Endpoints:** Dynamic routes for redirect, callback, and logout (`/login/keycloak`, `/login/keycloak/callback`, `/logout/keycloak`).
- **Flexible User Mapping:** Customizable JIT provisioning and user matching by `keycloak_id` (OIDC `sub`).
- **Post-Login Hook:** Support for custom role/permission syncing (e.g., Spatie roles).
- **Global Single Logout:** Clean front-channel/back-channel global logout with `id_token_hint` handling (bypasses Keycloak logout confirmation).
- **Laravel 10 / 11 / 12 / 13 Compatibility:** Supports PHP 8.2+ and all recent Laravel frameworks.

---

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

Once published to Packagist, you can install the package via:

```
composer require tesda/keycloak-auth
```

For local development/testing before publishing, configure the package as a path repository in your application's `composer.json`:

```
"repositories": [
    {
        "type": "path",
        "url": "../keycloak-auth"
    }
]
```

Then run:

```
composer require tesda/keycloak-auth:@dev
```

### 2. Publish Configuration & Migrations

[](#2-publish-configuration--migrations)

Publish the package configuration and database migration:

```
php artisan vendor:publish --provider="Tesda\KeycloakAuth\KeycloakAuthServiceProvider"
```

Run the migration to add the `keycloak_id` column to the `users` table:

```
php artisan migrate
```

---

Configuration
-------------

[](#configuration)

In your `.env` file, configure the following values:

```
KEYCLOAK_BASE_URL=http://localhost:8080
KEYCLOAK_REALM=tesda
KEYCLOAK_CLIENT_ID=your-app-client-id
KEYCLOAK_CLIENT_SECRET=your-app-client-secret
KEYCLOAK_REDIRECT_URI=http://your-app.test/login/keycloak/callback
KEYCLOAK_LOGIN_REDIRECT=/dashboard
KEYCLOAK_LOGOUT_REDIRECT=/
```

---

Customization
-------------

[](#customization)

### Custom User Mapping

[](#custom-user-mapping)

By default, the package maps the Keycloak user attributes to the local `User` model by searching for `keycloak_id`, linking by `email` if found without `keycloak_id`, or creating a new user JIT.

To customize this behavior:

1. Create a mapper class implementing `Tesda\KeycloakAuth\Contracts\UserMapper`:

```
namespace App\Services;

use Tesda\KeycloakAuth\Contracts\UserMapper;
use Laravel\Socialite\Contracts\User as SocialiteUser;

class CustomUserMapper implements UserMapper
{
    public function map(SocialiteUser $socialiteUser, string $userModelClass)
    {
        // Custom logic to find, link or create your user...
        return $user;
    }
}
```

2. Reference your class in `config/keycloak-auth.php`:

```
'user_mapper' => \App\Services\CustomUserMapper::class,
```

### Authorization Gate (restrict login to specific roles)

[](#authorization-gate-restrict-login-to-specific-roles)

By default any user who authenticates with Keycloak is provisioned and logged in. To restrict an application to holders of specific **realm roles** (e.g. an admin console), set `required_roles`. A user must hold **at least one** of the listed roles or they are denied — no local account is created and no session is started.

```
// config/keycloak-auth.php
'required_roles' => ['system-admin'],      // empty = no gate (default)
'unauthorized_redirect' => '/denied',      // where denied users are sent
```

Or via `.env`:

```
KEYCLOAK_REQUIRED_ROLES=system-admin       # comma-separated for multiple
KEYCLOAK_UNAUTHORIZED_REDIRECT=/denied
```

The gate runs on the callback, before user mapping/login, and reads the `realm_access.roles` claim from the token.

### Role Synchronization

[](#role-synchronization)

To sync roles (e.g. Spatie roles) upon successful login:

1. Create a syncer class implementing `Tesda\KeycloakAuth\Contracts\RoleSyncer`:

```
namespace App\Services;

use Tesda\KeycloakAuth\Contracts\RoleSyncer;
use Laravel\Socialite\Contracts\User as SocialiteUser;

class CustomRoleSyncer implements RoleSyncer
{
    public function sync($localUser, SocialiteUser $socialiteUser): void
    {
        // Extract roles from claims
        $roles = data_get($socialiteUser->user, 'realm_access.roles', []);

        // Sync to Spatie
        $localUser->syncRoles($roles);
    }
}
```

2. Reference your class in `config/keycloak-auth.php`:

```
'role_syncer' => \App\Services\CustomRoleSyncer::class,
```

---

Routes
------

[](#routes)

If `register_routes` is set to `true` in `config/keycloak-auth.php` (default), the following routes are registered:

- **Login Redirect:** `/login/keycloak` (Name: `keycloak.login`)
- **Login Callback:** `/login/keycloak/callback` (Name: `keycloak.callback`)
- **SSO Logout:** `/logout/keycloak` (Name: `keycloak.logout`) \[Accepts `GET` and `POST`\]

---

License
-------

[](#license)

This package is open-source software licensed under the [MIT license](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance94

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~20 days

Total

2

Last Release

25d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/74764886?v=4)[Prince Joseph Esteves](/maintainers/Nyanta2598)[@Nyanta2598](https://github.com/Nyanta2598)

---

Top Contributors

[![Nyanta2598](https://avatars.githubusercontent.com/u/74764886?v=4)](https://github.com/Nyanta2598 "Nyanta2598 (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tesda-keycloak-auth/health.svg)

```
[![Health](https://phpackages.com/badges/tesda-keycloak-auth/health.svg)](https://phpackages.com/packages/tesda-keycloak-auth)
```

###  Alternatives

[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

10.2k4.0k](/packages/leantime-leantime)[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)[nasirkhan/laravel-starter

A CMS like modular Laravel starter project.

1.4k2.7k](/packages/nasirkhan-laravel-starter)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3518.3k](/packages/duncanmcclean-statamic-cargo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)