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

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

ideable/laravel-keycloak-guard
==============================

Maintained Keycloak Guard for Laravel APIs

v1.6.5(3mo ago)0641↑83.3%[2 PRs](https://github.com/ideable/laravel-keycloak-guard/pulls)MITPHPPHP ^8.3CI passing

Since Mar 16Pushed 2mo agoCompare

[ Source](https://github.com/ideable/laravel-keycloak-guard)[ Packagist](https://packagist.org/packages/ideable/laravel-keycloak-guard)[ Docs](https://github.com/ideable/laravel-keycloak-guard)[ RSS](/packages/ideable-laravel-keycloak-guard/feed)WikiDiscussions master Synced 3w ago

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

 [![](https://camo.githubusercontent.com/dd6b7dc7e6dc1f33750810f3489e9bd3730e4db39fd67ab20812da3d837a0365/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69646561626c652f6c61726176656c2d6b6579636c6f616b2d67756172642e737667)](https://camo.githubusercontent.com/dd6b7dc7e6dc1f33750810f3489e9bd3730e4db39fd67ab20812da3d837a0365/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69646561626c652f6c61726176656c2d6b6579636c6f616b2d67756172642e737667) [![](https://camo.githubusercontent.com/42dec9123aaf0b35541a48ac6b3211dd587b6014afce6720c2211617dbd99591/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69646561626c652f6c61726176656c2d6b6579636c6f616b2d67756172642e737667)](https://camo.githubusercontent.com/42dec9123aaf0b35541a48ac6b3211dd587b6014afce6720c2211617dbd99591/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69646561626c652f6c61726176656c2d6b6579636c6f616b2d67756172642e737667)

Simple Keycloak Guard for Laravel
=================================

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

This package helps you authenticate users on a Laravel API based on JWT tokens generated from **Keycloak Server**.

Project status
--------------

[](#project-status)

This repository is the Ideable-maintained fork of the original `robsontenorio/laravel-keycloak-guard`.

This fork exists because the original package stopped providing a practical maintenance path for current Laravel projects. The upstream package remained pinned to a vulnerable `firebase/php-jwt` major version, and there was no timely response or release path to unblock consumers that needed to update securely.

Given that situation, Ideable resumed maintenance from a public fork so projects depending on this guard can keep moving without rewriting their Keycloak integration.

The immediate reason for maintaining the fork is to keep Laravel API projects on a supported dependency line and remove the legacy `firebase/php-jwt` constraint that pinned consumers to a vulnerable major version.

The goal of this fork is conservative maintenance:

- keep the existing Laravel integration contract stable
- publish compatible releases from the `ideable` namespace
- validate the package against modern PHP and Laravel versions

What changed in the Ideable fork
--------------------------------

[](#what-changed-in-the-ideable-fork)

- Composer package renamed to `ideable/laravel-keycloak-guard`
- JWT dependency moved to `firebase/php-jwt ^7.0`
- package support aligned with current Laravel projects on `php ^8.3`
- fork-owned releases and CI replace the unmaintained upstream delivery path

Adoption in existing projects
-----------------------------

[](#adoption-in-existing-projects)

For a new install:

```
composer require ideable/laravel-keycloak-guard
```

To replace the unmaintained upstream package in an existing project:

```
composer remove robsontenorio/laravel-keycloak-guard
composer require ideable/laravel-keycloak-guard:^1.6.4
```

If your lock file still keeps old transitive constraints around, run:

```
composer update ideable/laravel-keycloak-guard firebase/php-jwt --with-all-dependencies
```

After the replacement, you should not need to change application code or Laravel auth configuration.

The runtime contract is intentionally unchanged:

- keep using the `keycloak` auth driver
- keep using the `KeycloakGuard\\...` namespace
- keep using the same `config/keycloak.php` options
- keep protecting routes with `auth:api`

Requirements
============

[](#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  or

The flow
========

[](#the-flow)

 [![](flow.png)](flow.png)

1. The frontend user authenticates on Keycloak Server
2. The frontend user obtains a JWT token.
3. In another moment, the frontend user makes a request to some protected endpoint on a Laravel API, with that token.
4. 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.
5. If everything is ok, then find the user on database and authenticate it on my API.
6. Optionally, the user can be created / updated in the API users database.
7. Return response

Install
=======

[](#install)

Require the package

```
composer require ideable/laravel-keycloak-guard

```

**If you are using Lumen**, register the provider in your boostrap app file `bootstrap/app.php`.
For facades, uncomment `$app->withFacades();` in your boostrap app file `bootstrap/app.php`

```
$app->register(\KeycloakGuard\KeycloakGuardServiceProvider::class);
```

### Example configuration (.env)

[](#example-configuration-env)

```
KEYCLOAK_REALM_PUBLIC_KEY=MIIBIj...         # Get it on Keycloak admin web console.
KEYCLOAK_LOAD_USER_FROM_DATABASE=false      # You can opt to not load user from database, and use that one provided from JWT token.
KEYCLOAK_APPEND_DECODED_TOKEN=true          # Append the token info to user object.
KEYCLOAK_ALLOWED_RESOURCES=my-api           # The JWT token must contain this resource `my-api`.
KEYCLOAK_LEEWAY=60                          # Optional, but solve some weird issues with timestamps from JWT token.
```

### Auth Guard

[](#auth-guard)

Changes on `config/auth.php`

```
'defaults' => [
    'guard' => 'api',                 #  'users',
],
'guards' => [
    'api' => [
        'driver' => 'keycloak',       #  'users',
    ],
],
```

### Routes

[](#routes)

Just protect some endpoints on `routes/api.php` and **you are done!**

```
// public endpoints
Route::get('/hello', function () {
    return ':)';
});

// protected endpoints
Route::group(['middleware' => 'auth:api'], function () {
    Route::get('/protected-endpoint', 'SecretController@index');

    // more endpoints ...
});
```

Configuration
=============

[](#configuration)

Keycloak Guard
--------------

[](#keycloak-guard)

⚠️ When editing `.env` make sure all strings **are trimmed.**

```
# Publish config file

php artisan vendor:publish  --provider="KeycloakGuard\KeycloakGuardServiceProvider"
```

✔️ **realm\_public\_key**

*Required.*

The Keycloak Server realm public key (string).

> How to get realm public key? Click on "Realm Settings" > "Keys" > "Algorithm RS256 (or defined under token\_encryption\_algorithm configuration)" Line > "Public Key" Button

✔️ **token\_encryption\_algorithm**

*Default is `RS256`.*

The JWT token encryption algorithm used by Keycloak (string).

✔️ **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`.**Expects the string name of your custom defined method in your custom user provider.*

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](https://laravel.com/docs/8.x/authentication#adding-custom-user-providers).

If using this feature, the values defined for `user_provider_credential` and `token_principal_attribute` will be ignored. Requires 'load\_user\_from\_database' to be true. Your custom method needs the parameters $token (an object) and $credentials (an associative array).

✔️ **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 *resource\_access*. 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** *allowed\_resources* 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 "* try to set it `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.

```
// keycloak.php
'input_key' => 'api_token'

// If there is no Bearer token on request it will use `api_token` request param
GET  $this->get("/foo/secret?api_token=xxxxx")
POST $this->post("/foo/secret", ["api_token" => "xxxxx"])
```

API
===

[](#api)

Simple Keycloak Guard implements `Illuminate\Contracts\Auth\Guard`. So, all Laravel default methods will be available.

Default Laravel methods
-----------------------

[](#default-laravel-methods)

- `check()`
- `guest()`
- `user()`
- `id()`
- `validate()`
- `setUser()`

Keycloak Guard methods
----------------------

[](#keycloak-guard-methods)

#### Token

[](#token)

`token()`*Returns full decoded JWT token from authenticated user.*

```
$token = Auth::token()  // or Auth::user()->token()
```

#### Role

[](#role)

`hasRole('some-resource', 'some-role')`*Check if authenticated user has a role on resource\_access*

```
// Example decoded payload

'resource_access' => [
  'myapp-backend' => [
      'roles' => [
        'myapp-backend-role1',
        'myapp-backend-role2'
      ]
  ],
  'myapp-frontend' => [
    'roles' => [
      'myapp-frontend-role1',
      'myapp-frontend-role2'
    ]
  ]
]
```

```
Auth::hasRole('myapp-backend', 'myapp-backend-role1') // true
Auth::hasRole('myapp-frontend', 'myapp-frontend-role1') // true
Auth::hasRole('myapp-backend', 'myapp-frontend-role1') // false
```

`hasAnyRole('some-resource', ['some-role1', 'some-role2'])`*Check if the authenticated user has any of the roles in resource\_access*

```
Auth::hasAnyRole('myapp-backend', ['myapp-backend-role1', 'myapp-backend-role3']) // true
Auth::hasAnyRole('myapp-frontend', ['myapp-frontend-role1', 'myapp-frontend-role3']) // true
Auth::hasAnyRole('myapp-backend', ['myapp-frontend-role1', 'myapp-frontend-role2']) // false
```

#### Scope

[](#scope)

Example decoded payload:

```
{
    "scope": "scope-a scope-b scope-c",
}
```

`scopes()`*Get all user scopes*

```
array:3 [
  0 => "scope-a"
  1 => "scope-b"
  2 => "scope-c"
]
```

`hasScope('some-scope')`*Check if authenticated user has a scope*

```
Auth::hasScope('scope-a') // true
Auth::hasScope('scope-d') // false
```

`hasAnyScope(['scope-a', 'scope-c'])`*Check if the authenticated user has any of the scopes*

```
Auth::hasAnyScope(['scope-a', 'scope-c']) // true
Auth::hasAnyScope(['scope-a', 'scope-d']) // true
Auth::hasAnyScope(['scope-f', 'scope-k']) // false
```

Acting as a Keycloak user in tests
----------------------------------

[](#acting-as-a-keycloak-user-in-tests)

As an equivalent 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:

```
use KeycloakGuard\ActingAsKeycloakUser;

public test_a_protected_route()
{
    $this->actingAsKeycloakUser()
        ->getJson('/api/somewhere')
        ->assertOk();
}
```

If you are not using `keycloak.load_user_from_database` option, set `keycloak.preferred_username` with a valid `preferred_username` for tests.

You can also specify exact expectations for the token payload by passing the payload array in the second argument:

```
use KeycloakGuard\ActingAsKeycloakUser;

public test_a_protected_route()
{
    $this->actingAsKeycloakUser($user, [
        'aud' => 'account',
        'exp' => 1715926026,
        'iss' => 'https://localhost:8443/realms/master'
    ])->getJson('/api/somewhere')
      ->assertOk();
}
```

`$user` argument receives a string identifier or an Eloquent model, identifier of which is expected to be the property referred in **user\_provider\_credential** config. Whatever you pass in the payload will override default claims, which includes `aud`, `iat`, `exp`, `iss`, `azp`, `resource_access` and either `sub` or `preferred_username`, depending on **token\_principal\_attribute** config.

Alternatively, payload can be provided in a class property, so it can be reused across multiple tests:

```
use KeycloakGuard\ActingAsKeycloakUser;

protected $tokenPayload = [
    'aud' => 'account',
    'exp' => 1715926026,
    'iss' => 'https://localhost:8443/realms/master'
];

public test_a_protected_route()
{
    $payload = [
        'exp' => 1715914352
    ];
    $this->actingAsKeycloakUser($user, $payload)
        ->getJson('/api/somewhere')
        ->assertOk();
}
```

Priority is given to the claims in passed as an argument, so they will override ones in the class property. `$user` argument has the highest priority over the claim referred in **token\_principal\_attribute** config.

Contribute
==========

[](#contribute)

You can run this project on VSCODE with Remote Container. Make sure you will use internal VSCODE terminal (inside running container).

```
composer install
composer test
composer test:coverage
```

Contact
=======

[](#contact)

Please use the GitHub issues tracker in this repository for maintenance and support of the Ideable fork.

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance84

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 53.1% 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 ~0 days

Total

2

Last Release

102d ago

PHP version history (2 changes)v1.6.4PHP ^8.2

v1.6.5PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/176cb31d65d3d316da10ef09193368a76388d042a7f88e704768fbf7126333dc?d=identicon)[newuni](/maintainers/newuni)

---

Top Contributors

[![robsontenorio](https://avatars.githubusercontent.com/u/118955?v=4)](https://github.com/robsontenorio "robsontenorio (26 commits)")[![newuni](https://avatars.githubusercontent.com/u/5380?v=4)](https://github.com/newuni "newuni (6 commits)")[![hamidhaghdoost](https://avatars.githubusercontent.com/u/8298095?v=4)](https://github.com/hamidhaghdoost "hamidhaghdoost (2 commits)")[![vlauciani](https://avatars.githubusercontent.com/u/16477095?v=4)](https://github.com/vlauciani "vlauciani (2 commits)")[![frital](https://avatars.githubusercontent.com/u/17753531?v=4)](https://github.com/frital "frital (1 commits)")[![luizjr](https://avatars.githubusercontent.com/u/1474563?v=4)](https://github.com/luizjr "luizjr (1 commits)")[![marwins](https://avatars.githubusercontent.com/u/20090626?v=4)](https://github.com/marwins "marwins (1 commits)")[![Androbin](https://avatars.githubusercontent.com/u/16437156?v=4)](https://github.com/Androbin "Androbin (1 commits)")[![OfficialBAMM](https://avatars.githubusercontent.com/u/10955512?v=4)](https://github.com/OfficialBAMM "OfficialBAMM (1 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")[![ptrgast](https://avatars.githubusercontent.com/u/10983711?v=4)](https://github.com/ptrgast "ptrgast (1 commits)")[![roberto-proj](https://avatars.githubusercontent.com/u/121515667?v=4)](https://github.com/roberto-proj "roberto-proj (1 commits)")[![SolveSoul](https://avatars.githubusercontent.com/u/6033289?v=4)](https://github.com/SolveSoul "SolveSoul (1 commits)")[![matsver](https://avatars.githubusercontent.com/u/42805709?v=4)](https://github.com/matsver "matsver (1 commits)")[![antonkomarev](https://avatars.githubusercontent.com/u/1849174?v=4)](https://github.com/antonkomarev "antonkomarev (1 commits)")[![dfeneck](https://avatars.githubusercontent.com/u/78724526?v=4)](https://github.com/dfeneck "dfeneck (1 commits)")[![elnurvl](https://avatars.githubusercontent.com/u/7970970?v=4)](https://github.com/elnurvl "elnurvl (1 commits)")

---

Tags

laravelkeycloak

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

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

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

###  Alternatives

[robsontenorio/laravel-keycloak-guard

🔑 Simple Keycloak Guard for Laravel

5181.1M3](/packages/robsontenorio-laravel-keycloak-guard)[stevenmaguire/oauth2-keycloak

Keycloak OAuth 2.0 Client Provider for The PHP League OAuth2-Client

2276.2M36](/packages/stevenmaguire-oauth2-keycloak)[ellaisys/aws-cognito

AWS Cognito package that allows Auth and other related features using the AWS SDK for PHP

121242.9k1](/packages/ellaisys-aws-cognito)[kovah/laravel-socialite-oidc

OpenID Connect OAuth2 Provider for Laravel Socialite

24110.5k](/packages/kovah-laravel-socialite-oidc)

PHPackages © 2026

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