PHPackages                             udevrandom/laravel-keycloak-web-guard - 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. udevrandom/laravel-keycloak-web-guard

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

udevrandom/laravel-keycloak-web-guard
=====================================

Simple Keycloak Guard to Laravel Web Routes

v2.3.11(5y ago)039MITPHP

Since Jun 5Pushed 5y agoCompare

[ Source](https://github.com/udevrandom/laravel-keycloak-web-guard)[ Packagist](https://packagist.org/packages/udevrandom/laravel-keycloak-web-guard)[ Docs](https://github.com/udevrandom/laravel-keycloak-web-guard)[ RSS](/packages/udevrandom-laravel-keycloak-web-guard/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (1)Versions (41)Used By (0)

 [![](https://camo.githubusercontent.com/1cf6553de5fdeb4194331d9404245b14bf531a6ca948c5d82c5abd4820d426d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76697a69722f6c61726176656c2d6b6579636c6f616b2d7765622d67756172642e737667)](https://camo.githubusercontent.com/1cf6553de5fdeb4194331d9404245b14bf531a6ca948c5d82c5abd4820d426d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76697a69722f6c61726176656c2d6b6579636c6f616b2d7765622d67756172642e737667) [![](https://camo.githubusercontent.com/a892f37e294a3ad46ad38f13cd85a6d4b763f94bba9e0b8d82172a386e3f1c8f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f76697a69722f6c61726176656c2d6b6579636c6f616b2d7765622d67756172642e737667)](https://camo.githubusercontent.com/a892f37e294a3ad46ad38f13cd85a6d4b763f94bba9e0b8d82172a386e3f1c8f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f76697a69722f6c61726176656c2d6b6579636c6f616b2d7765622d67756172642e737667)

Keycloak Web Guard for Laravel
==============================

[](#keycloak-web-guard-for-laravel)

This packages allow you authenticate users with [Keycloak Server](https://www.keycloak.org).

It works on front. For APIs we recommend [laravel-keycloak-guard](https://github.com/robsontenorio/laravel-keycloak-guard).

Requirements
------------

[](#requirements)

- Have a Keycloak Server.
- Have a realm configured and a client that accepts authentication.

### Support

[](#support)

This package was tested with:

- Laravel: 5.8 / 7
- Keycloak: 4.8.3.Final / 11.0.2

Any other version is not guaranteed to work.

*This is project is open source and maintained on my free time. So, if you have any problem you can open a Issue with all details (laravel version, keycloak version, the description of problem...) and I'll be happy to try to help.*

The flow
--------

[](#the-flow)

1. User access a guarded route and is redirected to Keycloak login.
2. User signin and obtains a code.
3. He's redirected to callback page and we change the code for a access token.
4. We store it on session and validate user.
5. User is logged.
6. We redirect the user to "redirect\_url" route (see config) or the intended one.

Install
-------

[](#install)

Require the package

```
composer require udevrandom/laravel-keycloak-web-guard

```

If you want to change routes or the default values for Keycloak, publish the config file:

```
php artisan vendor:publish  --provider="Vizir\KeycloakWebGuard\KeycloakWebGuardServiceProvider"

```

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

[](#configuration)

After publishing `config/keycloak-web.php` file, you can change the routes:

```
'redirect_url' => '/admin',

'routes' => [
    'login' => 'login',
    'logout' => 'logout',
    'register' => 'register',
    'callback' => 'callback',
]
```

Change any value to change the URL.

Other configurations can be changed to have a new default value, but we recommend to use `.env` file:

- `KEYCLOAK_BASE_URL`

The Keycloak Server url. Generally is something like: `https://your-domain.com/auth`.

- `KEYCLOAK_REALM`

The Keycloak realm. The default is `master`.

- `KEYCLOAK_REALM_PUBLIC_KEY`

The Keycloak Server realm public key (string).

In dashboard go to: Keycloak >> Realm Settings >> Keys >> RS256 >> Public Key.

- `KEYCLOAK_CLIENT_ID`

Keycloak Client ID.

In dashboard go to: Keycloak >> Clients >> Installation.

- `KEYCLOAK_CLIENT_SECRET`

Keycloak Client Secret. If empty we'll not send it to Token Endpoint.

In dashboard go to: Keycloak >> Clients >> Installation.

- `KEYCLOAK_CACHE_OPENID`

We can cache the OpenId Configuration: it's a list of endpoints we require to Keycloak.

If you activate it, *remember to flush the cache* when change the realm or url.

Just add the options you would like as an array to the" to "Just add the options you would like to guzzle\_options array on keycloak-web.php config file. For example:

Laravel Auth
------------

[](#laravel-auth)

You should add Keycloak Web guard to your `config/auth.php`.

Just add **keycloak-web** to "driver" option on configurations you want.

As my default is web, I add to it:

```
'guards' => [
    'web' => [
        'driver' => 'keycloak-web',
        'provider' => 'users',
    ],

    // ...
],
```

And change your provider config too:

```
'providers' => [
    'users' => [
        'driver' => 'keycloak-users',
        'model' => Vizir\KeycloakWebGuard\Models\KeycloakUser::class,
    ],

    // ...
]
```

**Note:** if you want use another User Model, check the FAQ *How to implement my Model?*.

API
---

[](#api)

We implement the `Illuminate\Contracts\Auth\Guard`. So, all Laravel default methods will be available.

Ex: `Auth::user()` returns the authenticated user.

Roles
-----

[](#roles)

You can check user has a role simply by `Auth::hasRole('role')`;

This method accept two parameters: the first is the role (string or array of strings) and the second is the resource.

If not provided, resource will be the client\_id, which is the regular check if you authenticating into this client to your front.

### Keycloak Web Gate

[](#keycloak-web-gate)

You can use [Laravel Authorization Gate](https://laravel.com/docs/7.x/authorization#gates) to check user against one or more roles (and resources).

For example, in your Controller you can check **one role**:

```
if (Gate::denies('keycloak-web', 'manage-account')) {
  return abort(403);
}
```

Or **multiple roles**:

```
if (Gate::denies('keycloak-web', ['manage-account'])) {
  return abort(403);
}
```

And **roles for a resource**:

```
if (Gate::denies('keycloak-web', 'manage-account', 'another-resource')) {
  return abort(403);
}
```

*This last use is not trivial, but you can extend the Guard to request authentication/authorization to multiple resources. By default, we request only the current client.*

### Keycloak Can Middleware

[](#keycloak-can-middleware)

If you do not want to use the Gate or already implemented middlewares, you can check user against one or more roles using the `keycloak-web-can` Middleware.

Add this to your Controller's `__construct` method:

```
$this->middleware('keycloak-web-can:manage-something-cool');

// For multiple roles, separate with '|'
$this->middleware('keycloak-web-can:manage-something-cool|manage-something-nice|manage-my-application');
```

This middleware works searching for all roles on default resource (client\_id). It requires that all roles exist on the logged in user.

To check if a user has at least 1 provided role, use keycloak-web-hasany

```
$this->middleware('keycloak-web-hasany:manage-something-cool');

// For multiple roles, separate with '|'
$this->middleware('keycloak-web-hasany:view-app|manage-app|administer-app');
```

This middleware works by checking both the Client and Realm roles and if any of the provided roles match, it allows the traffic to pass. Otherwise, it presumes the user should see an error message indicating that while logged in, they are not authorized for the needed role.

You can extend it and register your own middleware on Kernel.php or just use `Auth::hasRole($roles, $resource)` on your Controller.

FAQ
---

[](#faq)

### How to implement my Model?

[](#how-to-implement-my-model)

We registered a new user provider that you configured on `config/auth.php` called "keycloak-users".

In this same configuration you setted the model. So you can register your own model extending `Vizir\KeycloakWebGuard\Models\KeycloakUser` class and changing this configuration.

You can implement your own [User Provider](https://laravel.com/docs/5.8/authentication#adding-custom-user-providers): just remember to implement the `retrieveByCredentials` method receiving the Keycloak Profile information to retrieve a instance of model.

Eloquent/Database User Provider should work well as they will parse the Keycloak Profile and make a "where" to your database. So your user data must match with Keycloak Profile.

### I cannot find my login form.

[](#i-cannot-find-my-login-form)

We register a `login` route to redirect to Keycloak Server. After login we'll receive and proccess the token to authenticate your user.

There's no login/registration form.

### How can I protect a route?

[](#how-can-i-protect-a-route)

Just add the `keycloak-web` middleware:

```
// On RouteServiceProvider.php for example

Route::prefix('admin')
  ->middleware('keycloak-web')
  ->namespace($this->namespace)
  ->group(base_path('routes/web.php'));

// Or with Route facade in another place

Route::group(['middleware' => 'keycloak-web'], function () {
    Route::get('/admin', 'Controller@admin');
});
```

### Where the access/refresh tokens and state are persisted?

[](#where-the-accessrefresh-tokens-and-state-are-persisted)

On session. We recommend implement the database driver if you have load balance.

### What's a state?

[](#whats-a-state)

State is a unique and non-guessable string used to mitigate CSRF attacks.

We associate each authentication request about to be initiated with one random state and check on callback. You should do it if you are extending/implementing your own Auth controller.

Use `KeycloakWeb::saveState()` method to save the already generated state to session and `KeycloakWeb::validateState()` to check the current state against the saved one.

### I'm having problems with session (stuck on login loop)

[](#im-having-problems-with-session-stuck-on-login-loop)

For some reason Laravel can present a problem with EncryptCookies middleware changing the session ID.

In this case, we will always try to login, as tokens cannot be retrieved.

You can remove session\_id cookie from encryption:

```
// On your EncryptCookies middleware

class EncryptCookies extends Middleware
{
    protected $except = [];

    public function __construct(EncrypterContract $encrypter)
    {
        parent::__construct($encrypter);

        /**
         * This will disable in runtime.
         *
         * If you have a "session.cookie" option or don't care about changing the app name
         * (in another environment, for example), you can only add it to "$except" array on top
         */
        $this->disableFor(config('session.cookie'));
    }
}
```

### My client is not public.

[](#my-client-is-not-public)

If your client is not public, you should provide a `KEYCLOAK_CLIENT_SECRET` on your `.env`.

### How can I override the default Guzzle options?

[](#how-can-i-override-the-default-guzzle-options)

In some use cases you may need to override the default Guzzle options - likely either to disable SSL verification or to set a Proxy to route all requests through.

Every \[[http://docs.guzzlephp.org/en/stable/request-options.html\](Guzzle](http://docs.guzzlephp.org/en/stable/request-options.html](Guzzle) Request Option) is supported and is passed directly to the Guzzle Client instance.

Just add the options you would like to `guzzle_options` array on `keycloak-web.php` config file. For example:

```
'guzzle_options' => [
    'verify' => false
]

```

Developers
----------

[](#developers)

- Mário Valney [@mariovalney](https://twitter.com/mariovalney)
- [Vizir Software Sutdio](https://vizir.com.br)

With contributors on GitHub ❤️

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 69.8% 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 ~14 days

Recently: every ~1 days

Total

40

Last Release

1957d ago

Major Versions

v1.5.6 → v2.0.02020-06-01

v1.5.7 → v2.2.02020-09-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/4254e1d67d403ed5f09663f374e0957e5fc2d8a756bb9fe1120642452b7a4ff8?d=identicon)[udevrandom](/maintainers/udevrandom)

---

Top Contributors

[![mariovalney](https://avatars.githubusercontent.com/u/5784633?v=4)](https://github.com/mariovalney "mariovalney (60 commits)")[![udevrandom](https://avatars.githubusercontent.com/u/7896803?v=4)](https://github.com/udevrandom "udevrandom (15 commits)")[![MatthewHallCom](https://avatars.githubusercontent.com/u/1230091?v=4)](https://github.com/MatthewHallCom "MatthewHallCom (8 commits)")[![agravelot](https://avatars.githubusercontent.com/u/13699253?v=4)](https://github.com/agravelot "agravelot (1 commits)")[![MartinCamen](https://avatars.githubusercontent.com/u/8720813?v=4)](https://github.com/MartinCamen "MartinCamen (1 commits)")[![Mnikoei](https://avatars.githubusercontent.com/u/19962633?v=4)](https://github.com/Mnikoei "Mnikoei (1 commits)")

---

Tags

jwtlaravelAuthenticationkeycloak

### Embed Badge

![Health badge](/badges/udevrandom-laravel-keycloak-web-guard/health.svg)

```
[![Health](https://phpackages.com/badges/udevrandom-laravel-keycloak-web-guard/health.svg)](https://phpackages.com/packages/udevrandom-laravel-keycloak-web-guard)
```

###  Alternatives

[vizir/laravel-keycloak-web-guard

Simple Keycloak Guard to Laravel Web Routes

166574.1k](/packages/vizir-laravel-keycloak-web-guard)[benbjurstrom/cognito-jwt-guard

A laravel auth guard for JSON Web Tokens issued by Amazon AWS Cognito

1113.1k](/packages/benbjurstrom-cognito-jwt-guard)

PHPackages © 2026

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