├── .devcontainer
    ├── Dockerfile
    └── devcontainer.json
├── bird.png
├── flow.png
├── .gitignore
├── src
    ├── Exceptions
    │   ├── TokenException.php
    │   ├── UserNotFoundException.php
    │   ├── ResourceAccessNotAllowedException.php
    │   └── KeycloakGuardException.php
    ├── KeycloakGuardServiceProvider.php
    ├── Token.php
    ├── ActingAsKeycloakUser.php
    └── KeycloakGuard.php
├── tests
    ├── Models
    │   └── User.php
    ├── Factories
    │   └── UserFactory.php
    ├── Extensions
    │   └── CustomUserProvider.php
    ├── Controllers
    │   └── FooController.php
    ├── TestCase.php
    └── AuthenticateTest.php
├── phpunit.xml.dist
├── config
    └── keycloak.php
├── LICENSE
├── .php-cs-fixer.php
├── composer.json
├── .github
    └── workflows
    │   └── test.yaml
└── README.md


/.devcontainer/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM robsontenorio/laravel
2 | 
3 | 
4 | 


--------------------------------------------------------------------------------
/bird.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/robsontenorio/laravel-keycloak-guard/HEAD/bird.png


--------------------------------------------------------------------------------
/flow.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/robsontenorio/laravel-keycloak-guard/HEAD/flow.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | vendor
2 | .php_cs.cache
3 | .php-cs-fixer.cache
4 | .coverage/
5 | .phpunit.result.cache


--------------------------------------------------------------------------------
/src/Exceptions/TokenException.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | namespace KeycloakGuard\Exceptions;
4 | 
5 | class TokenException extends KeycloakGuardException
6 | {
7 | }
8 | 


--------------------------------------------------------------------------------
/src/Exceptions/UserNotFoundException.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | namespace KeycloakGuard\Exceptions;
4 | 
5 | class UserNotFoundException extends KeycloakGuardException
6 | {
7 | }
8 | 


--------------------------------------------------------------------------------
/src/Exceptions/ResourceAccessNotAllowedException.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | namespace KeycloakGuard\Exceptions;
4 | 
5 | class ResourceAccessNotAllowedException extends KeycloakGuardException
6 | {
7 | }
8 | 


--------------------------------------------------------------------------------
/tests/Models/User.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard\Tests\Models;
 4 | 
 5 | use Illuminate\Foundation\Auth\User as Authenticatable;
 6 | 
 7 | class User extends Authenticatable
 8 | {
 9 | }
10 | 


--------------------------------------------------------------------------------
/src/Exceptions/KeycloakGuardException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard\Exceptions;
 4 | 
 5 | class KeycloakGuardException extends \UnexpectedValueException
 6 | {
 7 |     public function __construct(string $message)
 8 |     {
 9 |         $this->message = "[Keycloak Guard] {$message}";
10 |     }
11 | }
12 | 


--------------------------------------------------------------------------------
/tests/Factories/UserFactory.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard\Tests\Factories;
 4 | 
 5 | use Illuminate\Database\Eloquent\Factories\Factory;
 6 | use KeycloakGuard\Tests\Models\User;
 7 | 
 8 | class UserFactory extends Factory
 9 | {
10 |     protected $model = User::class;
11 | 
12 |     public function definition()
13 |     {
14 |         return [
15 |             'username' => $this->faker->userName,
16 |         ];
17 |     }
18 | }
19 | 


--------------------------------------------------------------------------------
/tests/Extensions/CustomUserProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard\Tests\Extensions;
 4 | 
 5 | use Illuminate\Auth\EloquentUserProvider;
 6 | 
 7 | class CustomUserProvider extends EloquentUserProvider
 8 | {
 9 |     public function custom_retrieve(object $token, array $credentials)
10 |     {
11 |         $model = parent::retrieveByCredentials($credentials);
12 |         $model->customRetrieve = true;
13 | 
14 |         return $model;
15 |     }
16 | }
17 | 


--------------------------------------------------------------------------------
/tests/Controllers/FooController.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard\Tests\Controllers;
 4 | 
 5 | use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
 6 | use Illuminate\Http\Request;
 7 | use Illuminate\Routing\Controller as BaseController;
 8 | 
 9 | class FooController extends BaseController
10 | {
11 |     use AuthorizesRequests;
12 | 
13 |     public function secret(Request $request)
14 |     {
15 |         return 'protected';
16 |     }
17 | 
18 |     public function public(Request $request)
19 |     {
20 |         return 'public';
21 |     }
22 | }
23 | 


--------------------------------------------------------------------------------
/phpunit.xml.dist:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3 |          xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
 4 |          bootstrap="vendor/autoload.php"
 5 |          colors="true"
 6 |          printerClass="NunoMaduro\Collision\Adapters\Phpunit\Printer">
 7 |     <testsuites>
 8 |         <testsuite name="Test Suite">
 9 |             <directory>tests</directory>
10 |         </testsuite>
11 |     </testsuites>
12 |     <coverage processUncoveredFiles="true">
13 |         <include>
14 |             <directory suffix=".php">./src</directory>
15 |         </include>
16 |     </coverage>
17 |     <php>
18 |         <env name="DB_CONNECTION" value="testing"/>
19 |     </php>
20 |     
21 | </phpunit>


--------------------------------------------------------------------------------
/src/KeycloakGuardServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard;
 4 | 
 5 | use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
 6 | use Illuminate\Support\Facades\Auth;
 7 | 
 8 | class KeycloakGuardServiceProvider extends ServiceProvider
 9 | {
10 |     public function boot()
11 |     {
12 |         $this->publishes([__DIR__.'/../config/keycloak.php' => config_path('keycloak.php')], 'config');
13 |         $this->mergeConfigFrom(__DIR__.'/../config/keycloak.php', 'keycloak');
14 |     }
15 | 
16 |      public function register()
17 |      {
18 |          Auth::extend('keycloak', function ($app, $name, array $config) {
19 |              return new KeycloakGuard(Auth::createUserProvider($config['provider']), $app->request);
20 |          });
21 |      }
22 | }
23 | 


--------------------------------------------------------------------------------
/config/keycloak.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | return [
 4 |     'realm_public_key' => env('KEYCLOAK_REALM_PUBLIC_KEY', null),
 5 | 
 6 |     'token_encryption_algorithm' => env('KEYCLOAK_TOKEN_ENCRYPTION_ALGORITHM', 'RS256'),
 7 | 
 8 |     'load_user_from_database' => env('KEYCLOAK_LOAD_USER_FROM_DATABASE', true),
 9 | 
10 |     'user_provider_custom_retrieve_method' => env('KEYCLOAK_USER_PROVIDER_CUSTOM_RETRIEVE_METHOD', null),
11 | 
12 |     'user_provider_credential' => env('KEYCLOAK_USER_PROVIDER_CREDENTIAL', 'username'),
13 | 
14 |     'token_principal_attribute' => env('KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE', 'preferred_username'),
15 | 
16 |     'append_decoded_token' => env('KEYCLOAK_APPEND_DECODED_TOKEN', false),
17 | 
18 |     'allowed_resources' => env('KEYCLOAK_ALLOWED_RESOURCES', null),
19 | 
20 |     'ignore_resources_validation' => env('KEYCLOAK_IGNORE_RESOURCES_VALIDATION', false),
21 | 
22 |     'leeway' => env('KEYCLOAK_LEEWAY', 0),
23 | 
24 |     'input_key' => env('KEYCLOAK_TOKEN_INPUT_KEY', null)
25 | ];
26 | 


--------------------------------------------------------------------------------
/.devcontainer/devcontainer.json:
--------------------------------------------------------------------------------
 1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
 2 | // https://github.com/microsoft/vscode-dev-containers/tree/v0.245.0/containers/ubuntu
 3 | {
 4 | 	"name": "Laravel Keycloak Guard",
 5 | 	"remoteUser": "appuser",
 6 | 	"workspaceFolder": "/var/www/app",
 7 | 	"workspaceMount": "source=${localWorkspaceFolder},target=/var/www/app,type=bind",
 8 | 	"build": {
 9 | 		"dockerfile": "Dockerfile"	
10 | 	},	
11 | 	"settings": {
12 | 		"terminal.integrated.defaultProfile.linux": "zsh",
13 | 		"[php]": {
14 | 			"editor.defaultFormatter": "junstyle.php-cs-fixer",
15 | 			"editor.formatOnSave": true
16 | 		},
17 | 		"php-cs-fixer.executablePath": "/var/www/app/vendor/bin/php-cs-fixer",
18 | 		"php-cs-fixer.config": "/var/www/app/.php-cs-fixer.php",
19 | 		"php-cs-fixer.onsave": true
20 | 	},
21 | 	"remoteEnv": {
22 | 		"PHP_CS_FIXER_IGNORE_ENV": "1"
23 | 	},
24 | 	"extensions": [
25 | 		"bmewburn.vscode-intelephense-client",
26 | 		"junstyle.php-cs-fixer"
27 | 	]
28 | }
29 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2024 Robson Tenório
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/.php-cs-fixer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | use PhpCsFixer\Config;
 4 | use PhpCsFixer\Finder;
 5 | 
 6 | $rules = [
 7 |     '@PSR12' => true,
 8 |     'no_unused_imports' => true,
 9 |     'braces' => true,
10 |     'array_indentation' => true,
11 |     'whitespace_after_comma_in_array' => true,
12 |     'binary_operator_spaces' => true,
13 |     'no_extra_blank_lines' => true,
14 |     'method_chaining_indentation' => true,
15 |     'concat_space' => [
16 |         'spacing' => 'none',
17 |     ],
18 |     'ordered_imports' => [
19 |         'sort_algorithm' =>
20 |         'alpha',
21 |     ],
22 |     'class_attributes_separation' => [
23 |         'elements' => [
24 |             'method' => 'one',
25 |         ],
26 |     ],
27 |     'blank_line_before_statement' => [
28 |         'statements' => [
29 |             'if',
30 |             'break',
31 |             'continue',
32 |             'return',
33 |             'throw',
34 |             'try'
35 |         ],
36 |     ],
37 | ];
38 | 
39 | $finder = Finder::create()
40 |     ->in([
41 |         __DIR__ . '/src',
42 |         __DIR__ . '/config',        
43 |         __DIR__ . '/tests',
44 |     ])
45 |     ->name('*.php')
46 |     ->notName('*.blade.php')
47 |     ->ignoreDotFiles(true)
48 |     ->ignoreVCS(true)
49 | ;
50 | 
51 | return (new Config())
52 |     ->setFinder($finder)
53 |     ->setRules($rules)
54 |     ->setRiskyAllowed(true)
55 |     ->setUsingCache(true);
56 | 


--------------------------------------------------------------------------------
/src/Token.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard;
 4 | 
 5 | use Firebase\JWT\JWT;
 6 | use Firebase\JWT\Key;
 7 | 
 8 | class Token
 9 | {
10 |     /**
11 |      * Decode a JWT token
12 |      *
13 |      * @param  string  $token
14 |      * @param  string  $publicKey
15 |      * @return mixed|null
16 |      */
17 |     public static function decode(?string $token, string $publicKey, int $leeway = 0, string $algorithm = 'RS256')
18 |     {
19 |         JWT::$leeway = $leeway;
20 |         $publicKey = self::buildPublicKey($publicKey);
21 | 
22 |         return $token ? JWT::decode($token, new Key($publicKey, $algorithm)) : null;
23 |     }
24 | 
25 |     /**
26 |      * Build a valid public key from a string
27 |      *
28 |      * @param  string  $key
29 |      * @return mixed
30 |      */
31 |     private static function buildPublicKey(string $key)
32 |     {
33 |         return "-----BEGIN PUBLIC KEY-----\n".wordwrap($key, 64, "\n", true)."\n-----END PUBLIC KEY-----";
34 |     }
35 | 
36 |     /**
37 |      * Get the plain public key from a string
38 |      *
39 |      * @param  string  $key
40 |      * @return string
41 |      */
42 |     public static function plainPublicKey(string $key): string
43 |     {
44 |         $string = str_replace('-----BEGIN PUBLIC KEY-----', '', $key);
45 |         $string = trim(str_replace('-----END PUBLIC KEY-----', '', $string));
46 |         $string = str_replace('\n', '', $string);
47 | 
48 |         return $string;
49 |     }
50 | }
51 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "robsontenorio/laravel-keycloak-guard",
 3 |     "description": "🔑 Simple Keycloak Guard for Laravel",
 4 |     "keywords": [
 5 |         "laravel",
 6 |         "keycloak"
 7 |     ],
 8 |     "homepage": "https://github.com/robsontenorio/laravel-keycloak-guard",
 9 |     "license": "MIT",
10 |     "authors": [
11 |         {
12 |             "name": "Robson Tenório"
13 |         }
14 |     ],
15 |     "minimum-stability": "dev",
16 |     "prefer-stable": true,
17 |     "require": {
18 |         "firebase/php-jwt": "^6.3",
19 |         "php": "^8.0",
20 |         "ext-openssl": "*"
21 |     },
22 |     "autoload": {
23 |         "psr-4": {
24 |             "KeycloakGuard\\": "src/"
25 |         }
26 |     },
27 |     "autoload-dev": {
28 |         "psr-4": {
29 |             "KeycloakGuard\\Tests\\": "tests/"
30 |         }
31 |     },
32 |     "scripts": {
33 |         "test": "pest",
34 |         "test:coverage": "php -d pcov.enabled=1 ./vendor/bin/pest --coverage --coverage-clover=.coverage/clover.xml --coverage-html=.coverage",
35 |         "post-autoload-dump": [
36 |             "@php ./vendor/bin/testbench package:discover --ansi"
37 |         ]
38 |     },
39 |     "extra": {
40 |         "laravel": {
41 |             "providers": [
42 |                 "KeycloakGuard\\KeycloakGuardServiceProvider"
43 |             ]
44 |         }
45 |     },
46 |     "require-dev": {
47 |         "phpunit/phpunit": "^9.5",
48 |         "orchestra/testbench": "^7.7",
49 |         "friendsofphp/php-cs-fixer": "^3.10",
50 |         "nunomaduro/collision": "^6.3",
51 |         "pestphp/pest": "^1.22"
52 |     },
53 |     "config": {
54 |         "allow-plugins": {
55 |             "pestphp/pest-plugin": true
56 |         }
57 |     }
58 | }
59 | 


--------------------------------------------------------------------------------
/.github/workflows/test.yaml:
--------------------------------------------------------------------------------
 1 | name: Test package
 2 | 
 3 | on: [push, pull_request]
 4 | 
 5 | jobs:
 6 |   build-and-test:
 7 |     name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }} 
 8 |     runs-on: ubuntu-latest
 9 |     strategy:
10 |       matrix:
11 |         php: [8.0, 8.1]
12 |         laravel: [8.*, 9.*]       
13 |         stability: [prefer-lowest, prefer-stable]               
14 |         include: 
15 |           - laravel: 8.*
16 |             testbench: 6.*
17 |             collision: 5.*
18 |           - laravel: 9.*
19 |             testbench: 7.*
20 |             collision: 6.*
21 |         exclude:
22 |           - laravel: 8.*
23 |             stability: prefer-lowest
24 |                       
25 |     steps:
26 |       - name: Checkout code
27 |         uses: actions/checkout@v2
28 | 
29 |       - name: Cache dependencies
30 |         uses: actions/cache@v2
31 |         with:
32 |           path: ~/.composer/cache/files
33 |           key: dependencies-composer-${{ hashFiles('composer.json') }}
34 | 
35 |       - name: Setup PHP
36 |         uses: shivammathur/setup-php@v2
37 |         with:
38 |           php-version: ${{ matrix.php }}
39 |           # extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath
40 | 
41 |       - name: Install dependencies
42 |         run: |
43 |           composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" "nunomaduro/collision:${{ matrix.collision }}" --dev --no-interaction --no-update --ansi
44 |           composer update --${{ matrix.stability }} --prefer-dist --no-interaction --ansi
45 | 
46 |       - name: Execute tests
47 |         run: composer test:coverage
48 | 
49 |       - name: Upload to Codecov
50 |         uses: codecov/codecov-action@v2
51 |         with:
52 |           token: ${{ secrets.CODE_COV_TOKEN }}
53 |           files: .coverage/clover.xml
54 |           verbose: true


--------------------------------------------------------------------------------
/src/ActingAsKeycloakUser.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace KeycloakGuard;
 4 | 
 5 | use Firebase\JWT\JWT;
 6 | use Illuminate\Support\Facades\Config;
 7 | 
 8 | trait ActingAsKeycloakUser
 9 | {
10 |     protected array $jwtPayload = [];
11 | 
12 |     public function actingAsKeycloakUser($user = null, $payload = []): self
13 |     {
14 |         $principal = Config::get('keycloak.token_principal_attribute');
15 |         if (!$user && !isset($payload[$principal]) && !isset($this->jwtPayload[$principal])) {
16 |             Config::set('keycloak.load_user_from_database', false);
17 |         }
18 | 
19 |         $token = $this->generateKeycloakToken($user, $payload);
20 | 
21 |         $this->withHeader('Authorization', 'Bearer '.$token);
22 | 
23 |         return $this;
24 |     }
25 | 
26 |     public function generateKeycloakToken($user = null, $payload = []): string
27 |     {
28 |         $privateKey = openssl_pkey_new([
29 |             'digest_alg' => 'sha256',
30 |             'private_key_bits' => 1024,
31 |             'private_key_type' => OPENSSL_KEYTYPE_RSA
32 |         ]);
33 | 
34 |         $publicKey = openssl_pkey_get_details($privateKey)['key'];
35 | 
36 |         $publicKey = Token::plainPublicKey($publicKey);
37 | 
38 |         Config::set('keycloak.realm_public_key', $publicKey);
39 | 
40 |         $iat = time();
41 |         $exp = time() + 300;
42 |         $resourceAccess = [config('keycloak.allowed_resources') => []];
43 |         $principal = Config::get('keycloak.token_principal_attribute');
44 |         $credential = Config::get('keycloak.user_provider_credential');
45 | 
46 |         $payload = array_merge([
47 |             'iss' => 'https://keycloak.server/realms/laravel',
48 |             'azp' => 'client-id',
49 |             'aud' => 'phpunit',
50 |             'iat' => $iat,
51 |             'exp' => $exp,
52 |             $principal => config('keycloak.preferred_username'),
53 |             'resource_access' => $resourceAccess,
54 |         ], $this->jwtPayload, $payload);
55 | 
56 |         if ($user) {
57 |             $payload[$principal] = is_string($user) ? $user : $user->$credential;
58 |         }
59 | 
60 |         return JWT::encode($payload, $privateKey, 'RS256');
61 |     }
62 | }
63 | 


--------------------------------------------------------------------------------
/tests/TestCase.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace KeycloakGuard\Tests;
  4 | 
  5 | use Firebase\JWT\JWT;
  6 | use Illuminate\Auth\Middleware\Authenticate;
  7 | use Illuminate\Database\Schema\Blueprint;
  8 | use Illuminate\Foundation\Application;
  9 | use Illuminate\Support\Facades\Route;
 10 | use KeycloakGuard\KeycloakGuardServiceProvider;
 11 | use KeycloakGuard\Tests\Factories\UserFactory;
 12 | use KeycloakGuard\Tests\Models\User;
 13 | use KeycloakGuard\Token;
 14 | use OpenSSLAsymmetricKey;
 15 | use Orchestra\Testbench\TestCase as Orchestra;
 16 | 
 17 | class TestCase extends Orchestra
 18 | {
 19 |     public OpenSSLAsymmetricKey $privateKey;
 20 |     public string $publicKey;
 21 |     public array $defaultPayload;
 22 |     public string $token;
 23 | 
 24 |     protected User $user;
 25 | 
 26 |     protected function setUp(): void
 27 |     {
 28 |         // Prepare credentials
 29 |         $this->prepareCredentials();
 30 | 
 31 |         parent::setUp();
 32 |         $this->withoutExceptionHandling();
 33 | 
 34 |         // bootstrap
 35 |         $this->setUpDatabase($this->app);
 36 | 
 37 |         // Default user, same as jwt token
 38 |         $this->user = UserFactory::new()->create([
 39 |             'username' => 'johndoe'
 40 |         ]);
 41 |     }
 42 | 
 43 |     protected function prepareCredentials(string $encryptionAlgorithm = 'RS256', ?array $openSSLConfig = null)
 44 |     {
 45 |         // Prepare private/public keys and a default JWT token, with a simple payload
 46 |         if (!$openSSLConfig) {
 47 |             $openSSLConfig = [
 48 |                 'digest_alg' => 'sha256',
 49 |                 'private_key_bits' => 1024,
 50 |                 'private_key_type' => OPENSSL_KEYTYPE_RSA
 51 |             ];
 52 |         }
 53 | 
 54 |         $this->privateKey = openssl_pkey_new($openSSLConfig);
 55 | 
 56 |         $this->publicKey = openssl_pkey_get_details($this->privateKey)['key'];
 57 | 
 58 |         $this->defaultPayload = [
 59 |             'preferred_username' => 'johndoe',
 60 |             'resource_access' => ['myapp-backend' => []]
 61 |         ];
 62 | 
 63 |         $this->token = JWT::encode($this->defaultPayload, $this->privateKey, $encryptionAlgorithm);
 64 |     }
 65 | 
 66 |     // Default configs to make it running
 67 |     protected function defineEnvironment($app)
 68 |     {
 69 |         $app['config']->set('auth.defaults.guard', 'api');
 70 |         $app['config']->set('auth.providers.users.model', User::class);
 71 | 
 72 |         $app['config']->set('auth.guards.api', [
 73 |             'driver' => 'keycloak',
 74 |             'provider' => 'users'
 75 |         ]);
 76 | 
 77 |         $app['config']->set('keycloak', [
 78 |             'realm_public_key' => Token::plainPublicKey($this->publicKey),
 79 |             'user_provider_credential' => 'username',
 80 |             'token_principal_attribute' => 'preferred_username',
 81 |             'append_decoded_token' => false,
 82 |             'allowed_resources' => 'myapp-backend',
 83 |             'ignore_resources_validation' => false,
 84 |         ]);
 85 |     }
 86 | 
 87 |     protected function setUpDatabase(Application $app)
 88 |     {
 89 |         $app['db']->connection()->getSchemaBuilder()->create('users', function (Blueprint $table) {
 90 |             $table->increments('id');
 91 |             $table->string('username');
 92 |             $table->timestamps();
 93 |         });
 94 |     }
 95 | 
 96 |     protected function getPackageProviders($app)
 97 |     {
 98 |         Route::any('/foo/secret', 'KeycloakGuard\Tests\Controllers\FooController@secret')->middleware(Authenticate::class);
 99 |         Route::any('/foo/public', 'KeycloakGuard\Tests\Controllers\FooController@public');
100 | 
101 |         return [KeycloakGuardServiceProvider::class];
102 |     }
103 | 
104 |     // Build a different token with custom payload
105 |     protected function buildCustomToken(array $payload, string $encryptionAlgorithm = 'RS256')
106 |     {
107 |         $payload = array_replace($this->defaultPayload, $payload);
108 | 
109 |         $this->token = JWT::encode($payload, $this->privateKey, $encryptionAlgorithm);
110 |     }
111 | 
112 |     // Setup default token, for the default user
113 |     public function withKeycloakToken()
114 |     {
115 |         $this->withToken($this->token);
116 | 
117 |         return $this;
118 |     }
119 | }
120 | 


--------------------------------------------------------------------------------
/src/KeycloakGuard.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace KeycloakGuard;
  4 | 
  5 | use Illuminate\Contracts\Auth\Authenticatable;
  6 | use Illuminate\Contracts\Auth\Guard;
  7 | use Illuminate\Contracts\Auth\UserProvider;
  8 | use Illuminate\Http\Request;
  9 | use KeycloakGuard\Exceptions\ResourceAccessNotAllowedException;
 10 | use KeycloakGuard\Exceptions\TokenException;
 11 | use KeycloakGuard\Exceptions\UserNotFoundException;
 12 | 
 13 | class KeycloakGuard implements Guard
 14 | {
 15 |     protected $config;
 16 |     protected $user;
 17 |     protected $provider;
 18 |     protected $decodedToken;
 19 |     protected Request $request;
 20 | 
 21 |     public function __construct(UserProvider $provider, Request $request)
 22 |     {
 23 |         $this->config = config('keycloak');
 24 |         $this->user = null;
 25 |         $this->provider = $provider;
 26 |         $this->decodedToken = null;
 27 |         $this->request = $request;
 28 | 
 29 |         $this->authenticate();
 30 |     }
 31 | 
 32 |     /**
 33 |      * Decode token, validate and authenticate user
 34 |      *
 35 |      * @return mixed
 36 |      */
 37 |     protected function authenticate()
 38 |     {
 39 |         try {
 40 |             $this->decodedToken = Token::decode($this->getTokenForRequest(), $this->config['realm_public_key'], $this->config['leeway'], $this->config['token_encryption_algorithm']);
 41 |         } catch (\Exception $e) {
 42 |             throw new TokenException($e->getMessage());
 43 |         }
 44 | 
 45 |         if ($this->decodedToken) {
 46 |             $this->validate([
 47 |                 $this->config['user_provider_credential'] => $this->decodedToken->{$this->config['token_principal_attribute']}
 48 |             ]);
 49 |         }
 50 |     }
 51 | 
 52 |     /**
 53 |      * Get the token for the current request.
 54 |      *
 55 |      * @return string
 56 |      */
 57 |     public function getTokenForRequest()
 58 |     {
 59 |         $inputKey = $this->config['input_key'] ?? "";
 60 | 
 61 |         return $this->request->bearerToken() ?? $this->request->input($inputKey);
 62 |     }
 63 | 
 64 |     /**
 65 |        * Determine if the current user is authenticated.
 66 |        *
 67 |        * @return bool
 68 |        */
 69 |     public function check()
 70 |     {
 71 |         return !is_null($this->user());
 72 |     }
 73 | 
 74 |     /**
 75 |      * Determine if the guard has a user instance.
 76 |      *
 77 |      * @return bool
 78 |      */
 79 |     public function hasUser()
 80 |     {
 81 |         return !is_null($this->user());
 82 |     }
 83 | 
 84 |     /**
 85 |      * Determine if the current user is a guest.
 86 |      *
 87 |      * @return bool
 88 |      */
 89 |     public function guest()
 90 |     {
 91 |         return !$this->check();
 92 |     }
 93 | 
 94 |      /**
 95 |      * Set the current user.
 96 |      *
 97 |      * @param  \Illuminate\Contracts\Auth\Authenticatable  $user
 98 |      * @return void
 99 |      */
100 |     public function setUser(Authenticatable $user)
101 |     {
102 |         $this->user = $user;
103 |     }
104 | 
105 |     /**
106 |      * Get the currently authenticated user.
107 |      *
108 |      * @return \Illuminate\Contracts\Auth\Authenticatable|null
109 |      */
110 |     public function user()
111 |     {
112 |         if (is_null($this->user)) {
113 |             return null;
114 |         }
115 | 
116 |         if ($this->config['append_decoded_token']) {
117 |             $this->user->token = $this->decodedToken;
118 |         }
119 | 
120 |         return $this->user;
121 |     }
122 | 
123 |     /**
124 |      * Get the ID for the currently authenticated user.
125 |      *
126 |      * @return int|null
127 |      */
128 |     public function id()
129 |     {
130 |         if ($user = $this->user()) {
131 |             return $this->user()->id;
132 |         }
133 |     }
134 | 
135 |      /**
136 |      * Returns full decoded JWT token from athenticated user
137 |      *
138 |      * @return mixed|null
139 |      */
140 |     public function token()
141 |     {
142 |         return json_encode($this->decodedToken);
143 |     }
144 | 
145 |     /**
146 |      * Validate a user's credentials.
147 |      *
148 |      * @param  array  $credentials
149 |      * @return bool
150 |      */
151 |     public function validate(array $credentials = [])
152 |     {
153 |         $this->validateResources();
154 | 
155 |         if ($this->config['load_user_from_database']) {
156 |             $methodOnProvider = $this->config['user_provider_custom_retrieve_method'] ?? null;
157 | 
158 |             if ($methodOnProvider) {
159 |                 $user = $this->provider->{$methodOnProvider}($this->decodedToken, $credentials);
160 |             } else {
161 |                 $user = $this->provider->retrieveByCredentials($credentials);
162 |             }
163 | 
164 |             if (!$user) {
165 |                 throw new UserNotFoundException("User not found. Credentials: ".json_encode($credentials));
166 |             }
167 |         } else {
168 |             $class = $this->provider->getModel();
169 |             $user = new $class();
170 |         }
171 | 
172 |         $this->setUser($user);
173 | 
174 |         return true;
175 |     }
176 | 
177 |     /**
178 |      * Validate if authenticated user has a valid resource
179 |      *
180 |      * @return void
181 |      */
182 |     protected function validateResources()
183 |     {
184 |         if ($this->config['ignore_resources_validation']) {
185 |             return;
186 |         }
187 | 
188 |         $token_resource_access = array_keys((array)($this->decodedToken->resource_access ?? []));
189 |         $allowed_resources = explode(',', $this->config['allowed_resources']);
190 | 
191 |         if (count(array_intersect($token_resource_access, $allowed_resources)) == 0) {
192 |             throw new ResourceAccessNotAllowedException("The decoded JWT token does not have a valid `resource_access` permission allowed by the API. Allowed resources: " . $this->config['allowed_resources'] . ". Token resources: " . json_encode($token_resource_access));
193 |         }
194 |     }
195 | 
196 |     /**
197 |      * Check if authenticated user has a especific role into resource
198 |      * @param string $resource
199 |      * @param string $role
200 |      * @return bool
201 |      */
202 |     public function hasRole($resource, $role)
203 |     {
204 |         $token_resource_access = (array)$this->decodedToken->resource_access;
205 | 
206 |         if (array_key_exists($resource, $token_resource_access)) {
207 |             $token_resource_values = (array)$token_resource_access[$resource];
208 | 
209 |             if (array_key_exists('roles', $token_resource_values) &&
210 |               in_array($role, $token_resource_values['roles'])) {
211 |                 return true;
212 |             }
213 |         }
214 | 
215 |         return false;
216 |     }
217 |     
218 |     /**
219 |      * Check if authenticated user has a any role into resource
220 |      * @param string $resource
221 |      * @param string $role
222 |      * @return bool
223 |      */
224 |     public function hasAnyRole($resource, array $roles)
225 |     {
226 |         $token_resource_access = (array)$this->decodedToken->resource_access;
227 | 
228 |         if (array_key_exists($resource, $token_resource_access)) {
229 |             $token_resource_values = (array)$token_resource_access[$resource];
230 | 
231 |             if (array_key_exists('roles', $token_resource_values)) {
232 |                 foreach ($roles as $role) {
233 |                     if (in_array($role, $token_resource_values['roles'])) {
234 |                         return true;
235 |                     }
236 |                 }
237 |             }
238 |         }
239 | 
240 |         return false;
241 |     }
242 | 
243 |     /**
244 |      * Get scope(s)
245 |      * @return array
246 |      */
247 |     public function scopes(): array
248 |     {
249 |         $scopes = $this->decodedToken->scope ?? null;
250 | 
251 |         if ($scopes) {
252 |             return explode(' ', $scopes);
253 |         }
254 | 
255 |         return [];
256 |     }
257 | 
258 |     /**
259 |      * Check if authenticated user has a especific scope
260 |      * @param string $scope
261 |      * @return bool
262 |      */
263 |     public function hasScope(string $scope): bool
264 |     {
265 |         $scopes = $this->scopes();
266 | 
267 |         if (in_array($scope, $scopes)) {
268 |             return true;
269 |         }
270 | 
271 |         return false;
272 |     }
273 | 
274 |     /**
275 |      * Check if authenticated user has a any scope
276 |      * @param array $scopes
277 |      * @return bool
278 |      */
279 |     public function hasAnyScope(array $scopes): bool
280 |     {
281 |         return count(array_intersect(
282 |             $this->scopes(),
283 |             is_string($scopes) ? [$scopes] : $scopes
284 |         )) > 0;
285 |     }
286 | }
287 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | <p align="center">
  2 |   <img src="bird.png">
  3 | </p>
  4 | <p align="center">
  5 | &nbsp;
  6 |         <img src="https://img.shields.io/packagist/v/robsontenorio/laravel-keycloak-guard.svg" />
  7 |         <img src="https://img.shields.io/packagist/dt/robsontenorio/laravel-keycloak-guard.svg" />
  8 |       <img src="https://codecov.io/gh/robsontenorio/laravel-keycloak-guard/branch/master/graph/badge.svg?token=8ZpDarpss1"/>
  9 | 
 10 | </p>
 11 | 
 12 | # Simple Keycloak Guard for Laravel
 13 | 
 14 | This package helps you authenticate users on a Laravel API based on JWT tokens generated from **Keycloak Server**.
 15 | 
 16 | # Requirements
 17 | 
 18 | ✔️ I`m building an API with Laravel.
 19 | 
 20 | ✔️ I will not use Laravel Passport for authentication, because Keycloak Server will do the job.
 21 | 
 22 | ✔️ The frontend is a separated project.
 23 | 
 24 | ✔️ The frontend users authenticate **directly on Keycloak Server** to obtain a JWT token. This process have nothing to do with the Laravel API.
 25 | 
 26 | ✔️ The frontend keep the JWT token from Keycloak Server.
 27 | 
 28 | ✔️ The frontend make requests to the Laravel API, with that token.
 29 | 
 30 | 💔 If your app does not match requirements, probably you are looking for https://socialiteproviders.com/Keycloak or https://github.com/Vizir/laravel-keycloak-web-guard
 31 | 
 32 | # The flow
 33 | 
 34 | <p align="center">
 35 |   <img src="flow.png">
 36 | </p>
 37 | 
 38 | 1. The frontend user authenticates on Keycloak Server
 39 | 
 40 | 1. The frontend user obtains a JWT token.
 41 | 
 42 | 1. In another moment, the frontend user makes a request to some protected endpoint on a Laravel API, with that token.
 43 | 
 44 | 1. The Laravel API (through `Keycloak Guard`) handle it.
 45 | 
 46 |    - Verify token signature.
 47 |    - Verify token structure.
 48 |    - Verify token expiration time.
 49 |    - Verify if my API allows `resource access` from token.
 50 | 
 51 | 1. If everything is ok, then find the user on database and authenticate it on my API.
 52 | 
 53 | 1. Optionally, the user can be created / updated in the API users database.
 54 | 
 55 | 1. Return response
 56 | 
 57 | # Install
 58 | 
 59 | Require the package
 60 | 
 61 | ```
 62 | composer require robsontenorio/laravel-keycloak-guard
 63 | ```
 64 | 
 65 | **If you are using Lumen**, register the provider in your boostrap app file `bootstrap/app.php`.  
 66 | For facades, uncomment `$app->withFacades();` in your boostrap app file `bootstrap/app.php`
 67 | 
 68 | ```php
 69 | $app->register(\KeycloakGuard\KeycloakGuardServiceProvider::class);
 70 | ```
 71 | 
 72 | ### Example configuration (.env)
 73 | 
 74 | ```.env
 75 | KEYCLOAK_REALM_PUBLIC_KEY=MIIBIj...         # Get it on Keycloak admin web console.
 76 | KEYCLOAK_LOAD_USER_FROM_DATABASE=false      # You can opt to not load user from database, and use that one provided from JWT token.
 77 | KEYCLOAK_APPEND_DECODED_TOKEN=true          # Append the token info to user object.
 78 | KEYCLOAK_ALLOWED_RESOURCES=my-api           # The JWT token must contain this resource `my-api`.
 79 | KEYCLOAK_LEEWAY=60                          # Optional, but solve some weird issues with timestamps from JWT token.
 80 | ```
 81 | 
 82 | 
 83 | ### Auth Guard
 84 | 
 85 | Changes on `config/auth.php`
 86 | 
 87 | ```php
 88 | 'defaults' => [
 89 |     'guard' => 'api',                 # <-- This
 90 |     'passwords' => 'users',
 91 | ],    
 92 | 'guards' => [
 93 |     'api' => [
 94 |         'driver' => 'keycloak',       # <-- This
 95 |         'provider' => 'users',
 96 |     ],
 97 | ],
 98 | ```
 99 | 
100 | ### Routes
101 | 
102 | Just protect some endpoints on `routes/api.php` and **you are done!**
103 | 
104 | ```php
105 | // public endpoints
106 | Route::get('/hello', function () {
107 |     return ':)';
108 | });
109 | 
110 | // protected endpoints
111 | Route::group(['middleware' => 'auth:api'], function () {
112 |     Route::get('/protected-endpoint', 'SecretController@index');
113 | 
114 |     // more endpoints ...
115 | });
116 | ```
117 | 
118 | 
119 | # Configuration
120 | 
121 | ## Keycloak Guard
122 | 
123 | ⚠️ When editing `.env` make sure all strings **are trimmed.**
124 | 
125 | ```bash
126 | # Publish config file
127 | 
128 | php artisan vendor:publish  --provider="KeycloakGuard\KeycloakGuardServiceProvider"
129 | ```
130 | 
131 | ✔️ **realm_public_key**
132 | 
133 | _Required._
134 | 
135 | The Keycloak Server realm public key (string).
136 | 
137 | > How to get realm public key? Click on "Realm Settings" > "Keys" > "Algorithm RS256 (or defined under token_encryption_algorithm configuration)" Line > "Public Key" Button
138 | 
139 | ✔️ **token_encryption_algorithm**
140 | 
141 | _Default is `RS256`._
142 | 
143 | The JWT token encryption algorithm used by Keycloak (string).
144 | 
145 | ✔️ **load_user_from_database**
146 | 
147 | _Required. Default is `true`._
148 | 
149 | If you do not have an `users` table you must disable this.
150 | 
151 | 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`.
152 | 
153 | ✔️ **user_provider_custom_retrieve_method**
154 | 
155 | _Default is `null`._
156 | _Expects the string name of your custom defined method in your custom user provider._
157 | 
158 | 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).
159 | 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).
160 | 
161 | 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).
162 | 
163 | ✔️ **user_provider_credential**
164 | 
165 | _Required.
166 | Default is `username`._
167 | 
168 | 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.
169 | 
170 | ✔️ **token_principal_attribute**
171 | 
172 | _Required.
173 | Default is `preferred_username`._
174 | 
175 | The property from JWT token that contains the user identifier.
176 | This will be confronted against `user_provider_credential` attribute, while authenticating.
177 | 
178 | ✔️ **append_decoded_token**
179 | 
180 | _Default is `false`._
181 | 
182 | 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.
183 | 
184 | ✔️ **allowed_resources**
185 | 
186 | _Required_.
187 | 
188 | 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.
189 | 
190 | ✔️ **ignore_resources_validation**
191 | 
192 | _Default is `false`_.
193 | 
194 | Disables entirely resources validation. It will **ignore** _allowed_resources_ configuration.
195 | 
196 | ✔️ **leeway**
197 | 
198 | _Default is `0`_.
199 | 
200 | 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 <DATE>"_ try to set it `60` (seconds).
201 | 
202 | ✔️ **input_key**
203 | 
204 | _Default is `null`._
205 | 
206 | 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.
207 | 
208 | ```php
209 | // keycloak.php
210 | 'input_key' => 'api_token'
211 | 
212 | // If there is no Bearer token on request it will use `api_token` request param
213 | GET  $this->get("/foo/secret?api_token=xxxxx")
214 | POST $this->post("/foo/secret", ["api_token" => "xxxxx"])
215 | ```
216 | 
217 | 
218 | # API
219 | 
220 | Simple Keycloak Guard implements `Illuminate\Contracts\Auth\Guard`. So, all Laravel default methods will be available.
221 | 
222 | ## Default Laravel methods
223 | 
224 | - `check()`
225 | - `guest()`
226 | - `user()`
227 | - `id()`
228 | - `validate()`
229 | - `setUser()`
230 | 
231 | ## Keycloak Guard methods
232 | 
233 | #### Token
234 | `token()`
235 | _Returns full decoded JWT token from authenticated user._
236 | 
237 | ```php
238 | $token = Auth::token()  // or Auth::user()->token()
239 | ```
240 | 
241 | #### Role
242 | `hasRole('some-resource', 'some-role')`
243 | _Check if authenticated user has a role on resource_access_
244 | 
245 | ```php
246 | // Example decoded payload
247 | 
248 | 'resource_access' => [
249 |   'myapp-backend' => [
250 |       'roles' => [
251 |         'myapp-backend-role1',
252 |         'myapp-backend-role2'
253 |       ]
254 |   ],
255 |   'myapp-frontend' => [
256 |     'roles' => [
257 |       'myapp-frontend-role1',
258 |       'myapp-frontend-role2'
259 |     ]
260 |   ]
261 | ]
262 | ```
263 | 
264 | ```php
265 | Auth::hasRole('myapp-backend', 'myapp-backend-role1') // true
266 | Auth::hasRole('myapp-frontend', 'myapp-frontend-role1') // true
267 | Auth::hasRole('myapp-backend', 'myapp-frontend-role1') // false
268 | ```
269 | 
270 | `hasAnyRole('some-resource', ['some-role1', 'some-role2'])`
271 | _Check if the authenticated user has any of the roles in resource_access_
272 | 
273 | ```php
274 | Auth::hasAnyRole('myapp-backend', ['myapp-backend-role1', 'myapp-backend-role3']) // true
275 | Auth::hasAnyRole('myapp-frontend', ['myapp-frontend-role1', 'myapp-frontend-role3']) // true
276 | Auth::hasAnyRole('myapp-backend', ['myapp-frontend-role1', 'myapp-frontend-role2']) // false
277 | ```
278 | 
279 | #### Scope
280 | Example decoded payload:
281 | ```json
282 | {
283 |     "scope": "scope-a scope-b scope-c",
284 | }
285 | ```
286 | 
287 | `scopes()`
288 | _Get all user scopes_
289 | 
290 | ```php
291 | array:3 [
292 |   0 => "scope-a"
293 |   1 => "scope-b"
294 |   2 => "scope-c"
295 | ]
296 | ```
297 | 
298 | `hasScope('some-scope')`
299 | _Check if authenticated user has a scope_
300 | 
301 | ```php
302 | Auth::hasScope('scope-a') // true
303 | Auth::hasScope('scope-d') // false
304 | ```
305 | 
306 | `hasAnyScope(['scope-a', 'scope-c'])`
307 | _Check if the authenticated user has any of the scopes_
308 | 
309 | ```php
310 | Auth::hasAnyScope(['scope-a', 'scope-c']) // true
311 | Auth::hasAnyScope(['scope-a', 'scope-d']) // true
312 | Auth::hasAnyScope(['scope-f', 'scope-k']) // false
313 | ```
314 | 
315 | ## Acting as a Keycloak user in tests
316 | 
317 | 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:
318 | 
319 | ```php
320 | use KeycloakGuard\ActingAsKeycloakUser;
321 | 
322 | public test_a_protected_route()
323 | {
324 |     $this->actingAsKeycloakUser()
325 |         ->getJson('/api/somewhere')
326 |         ->assertOk();
327 | }
328 | ```
329 | 
330 | If you are not using `keycloak.load_user_from_database` option, set `keycloak.preferred_username` with a valid `preferred_username` for tests.
331 | 
332 | You can also specify exact expectations for the token payload by passing the payload array in the second argument:
333 | 
334 | ```php
335 | use KeycloakGuard\ActingAsKeycloakUser;
336 | 
337 | public test_a_protected_route()
338 | {
339 |     $this->actingAsKeycloakUser($user, [
340 |         'aud' => 'account',
341 |         'exp' => 1715926026,
342 |         'iss' => 'https://localhost:8443/realms/master'
343 |     ])->getJson('/api/somewhere')
344 |       ->assertOk();
345 | }
346 | ```
347 | `$user` argument receives a string identifier or
348 | an Eloquent model, identifier of which is expected to be the property referred in **user_provider_credential** config.
349 | Whatever you pass in the payload will override default claims,
350 | which includes `aud`, `iat`, `exp`, `iss`, `azp`, `resource_access` and either `sub` or `preferred_username`,
351 | depending on **token_principal_attribute** config.
352 | 
353 | Alternatively, payload can be provided in a class property, so it can be reused across multiple tests:
354 | 
355 | ```php
356 | use KeycloakGuard\ActingAsKeycloakUser;
357 | 
358 | protected $tokenPayload = [
359 |     'aud' => 'account',
360 |     'exp' => 1715926026,
361 |     'iss' => 'https://localhost:8443/realms/master'
362 | ];
363 | 
364 | public test_a_protected_route()
365 | {
366 |     $payload = [
367 |         'exp' => 1715914352
368 |     ];
369 |     $this->actingAsKeycloakUser($user, $payload)
370 |         ->getJson('/api/somewhere')
371 |         ->assertOk();
372 | }
373 | ```
374 | 
375 | Priority is given to the claims in passed as an argument, so they will override ones in the class property.
376 | `$user` argument has the highest priority over the claim referred in **token_principal_attribute** config.
377 | 
378 | # Contribute
379 | 
380 | You can run this project on VSCODE with Remote Container. Make sure you will use internal VSCODE terminal (inside running container).
381 | 
382 | ```bash
383 | composer install
384 | composer test
385 | composer test:coverage
386 | ```
387 | 
388 | # Contact
389 | 
390 | Twitter [@robsontenorio](https://twitter.com/robsontenorio)
391 | 


--------------------------------------------------------------------------------
/tests/AuthenticateTest.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace KeycloakGuard\Tests;
  4 | 
  5 | use Firebase\JWT\JWT;
  6 | use Illuminate\Auth\AuthenticationException;
  7 | use Illuminate\Hashing\BcryptHasher;
  8 | use Illuminate\Support\Facades\Auth;
  9 | use KeycloakGuard\ActingAsKeycloakUser;
 10 | use KeycloakGuard\Exceptions\ResourceAccessNotAllowedException;
 11 | use KeycloakGuard\Exceptions\TokenException;
 12 | use KeycloakGuard\Exceptions\UserNotFoundException;
 13 | use KeycloakGuard\KeycloakGuard;
 14 | use KeycloakGuard\Tests\Extensions\CustomUserProvider;
 15 | use KeycloakGuard\Tests\Factories\UserFactory;
 16 | use KeycloakGuard\Tests\Models\User;
 17 | use KeycloakGuard\Token;
 18 | 
 19 | class AuthenticateTest extends TestCase
 20 | {
 21 |     use ActingAsKeycloakUser;
 22 | 
 23 |     protected function setUp(): void
 24 |     {
 25 |         parent::setUp();
 26 |     }
 27 | 
 28 |     public function test_authenticates_the_user_when_requesting_a_private_endpoint_with_token()
 29 |     {
 30 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
 31 |         $this->assertEquals($this->user->username, Auth::user()->username);
 32 | 
 33 |         $this->withKeycloakToken()->json('POST', '/foo/secret');
 34 |         $this->assertEquals($this->user->username, Auth::user()->username);
 35 | 
 36 |         $this->withKeycloakToken()->json('PUT', '/foo/secret');
 37 |         $this->assertEquals($this->user->username, Auth::user()->username);
 38 | 
 39 |         $this->withKeycloakToken()->json('PATCH', '/foo/secret');
 40 |         $this->assertEquals($this->user->username, Auth::user()->username);
 41 | 
 42 |         $this->withKeycloakToken()->json('DELETE', '/foo/secret');
 43 |         $this->assertEquals($this->user->username, Auth::user()->username);
 44 |     }
 45 | 
 46 |     public function test_authenticates_the_user_when_requesting_an_public_endpoint_with_token()
 47 |     {
 48 |         $this->withKeycloakToken()->json('GET', '/foo/public');
 49 | 
 50 |         $this->assertEquals($this->user->username, Auth::user()->username);
 51 |     }
 52 | 
 53 |     public function test_forbiden_when_request_a_protected_endpoint_without_token()
 54 |     {
 55 |         $this->expectException(AuthenticationException::class);
 56 |         $this->json('GET', '/foo/secret');
 57 |     }
 58 | 
 59 |     public function test_laravel_default_interface_for_authenticated_users()
 60 |     {
 61 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
 62 | 
 63 |         $this->assertEquals(Auth::hasUser(), true);
 64 |         $this->assertEquals(Auth::guest(), false);
 65 |         $this->assertEquals(Auth::id(), $this->user->id);
 66 |     }
 67 | 
 68 |     public function test_laravel_default_interface_for_unathenticated_users()
 69 |     {
 70 |         $this->json('GET', '/foo/public');
 71 | 
 72 |         $this->assertEquals(Auth::hasUser(), false);
 73 |         $this->assertEquals(Auth::guest(), true);
 74 |         $this->assertEquals(Auth::id(), null);
 75 |     }
 76 | 
 77 |     public function test_throws_a_exception_when_user_is_not_found()
 78 |     {
 79 |         $this->expectException(UserNotFoundException::class);
 80 | 
 81 |         $this->buildCustomToken([
 82 |             'preferred_username' => 'mary'
 83 |         ]);
 84 | 
 85 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
 86 |     }
 87 | 
 88 |     public function test_appends_token_to_the_user()
 89 |     {
 90 |         config(['keycloak.append_decoded_token' => true]);
 91 | 
 92 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
 93 | 
 94 |         $this->assertNotNull(Auth::user()->token);
 95 |         $this->assertEquals(json_decode(Auth::token()), Auth::user()->token);
 96 |     }
 97 | 
 98 |     public function test_does_not_appends_token_to_the_user()
 99 |     {
100 |         config(['keycloak.append_decoded_token' => false]);
101 | 
102 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
103 | 
104 |         $this->assertNull(Auth::user()->token);
105 |     }
106 | 
107 |     public function test_does_not_load_user_from_database()
108 |     {
109 |         config(['keycloak.load_user_from_database' => false]);
110 | 
111 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
112 | 
113 |         $this->assertCount(0, Auth::user()->getAttributes());
114 |     }
115 | 
116 |     public function test_does_not_load_user_from_database_but_appends_decoded_token()
117 |     {
118 |         config(['keycloak.load_user_from_database' => false]);
119 |         config(['keycloak.append_decoded_token' => true]);
120 | 
121 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
122 | 
123 |         $this->assertArrayHasKey('token', Auth::user()->toArray());
124 |     }
125 | 
126 |     public function test_throws_a_exception_when_resource_access_is_not_allowed_by_api()
127 |     {
128 |         $this->expectException(ResourceAccessNotAllowedException::class);
129 | 
130 |         $this->buildCustomToken([
131 |             'resource_access' => ['some_resouce_not_allowed' => []]
132 |         ]);
133 | 
134 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
135 |     }
136 | 
137 |     public function test_ignores_resources_validation()
138 |     {
139 |         config(['keycloak.ignore_resources_validation' => true]);
140 | 
141 |         $this->buildCustomToken([
142 |             'resource_access' => ['some_resouce_not_allowed' => []]
143 |         ]);
144 | 
145 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
146 | 
147 |         $this->assertEquals(Auth::id(), $this->user->id);
148 |     }
149 | 
150 |     public function test_check_user_has_role_in_resource()
151 |     {
152 |         $this->buildCustomToken([
153 |             'resource_access' => [
154 |                 'myapp-backend' => [
155 |                     'roles' => [
156 |                         'myapp-backend-role1',
157 |                         'myapp-backend-role2'
158 |                     ]
159 |                 ],
160 |                 'myapp-frontend' => [
161 |                     'roles' => [
162 |                         'myapp-frontend-role1',
163 |                         'myapp-frontend-role2'
164 |                     ]
165 |                 ]
166 |             ]
167 |         ]);
168 | 
169 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
170 |         $this->assertTrue(Auth::hasRole('myapp-backend', 'myapp-backend-role1'));
171 |     }
172 | 
173 |     public function test_check_user_no_has_role_in_resource()
174 |     {
175 |         $this->buildCustomToken([
176 |             'resource_access' => [
177 |                 'myapp-backend' => [
178 |                     'roles' => [
179 |                         'myapp-backend-role1',
180 |                         'myapp-backend-role2'
181 |                     ]
182 |                 ],
183 |                 'myapp-frontend' => [
184 |                     'roles' => [
185 |                         'myapp-frontend-role1',
186 |                         'myapp-frontend-role2'
187 |                     ]
188 |                 ]
189 |             ]
190 |         ]);
191 | 
192 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
193 |         $this->assertFalse(Auth::hasRole('myapp-backend', 'myapp-backend-role3'));
194 |     }
195 | 
196 |     public function test_prevent_cross_roles_resources()
197 |     {
198 |         $this->buildCustomToken([
199 |             'resource_access' => [
200 |                 'myapp-backend' => [
201 |                     'roles' => [
202 |                         'myapp-backend-role1',
203 |                         'myapp-backend-role2'
204 |                     ]
205 |                 ],
206 |                 'myapp-frontend' => [
207 |                     'roles' => [
208 |                         'myapp-frontend-role1',
209 |                         'myapp-frontend-role2'
210 |                     ]
211 |                 ]
212 |             ]
213 |         ]);
214 | 
215 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
216 |         $this->assertFalse(Auth::hasRole('myapp-backend', 'myapp-frontend-role1'));
217 |     }
218 | 
219 |     public function test_check_user_has_any_role_in_resource()
220 |     {
221 |         $this->buildCustomToken([
222 |             'resource_access' => [
223 |                 'myapp-backend' => [
224 |                     'roles' => [
225 |                         'myapp-backend-role1',
226 |                         'myapp-backend-role2'
227 |                     ]
228 |                 ],
229 |                 'myapp-frontend' => [
230 |                     'roles' => [
231 |                         'myapp-frontend-role1',
232 |                         'myapp-frontend-role2'
233 |                     ]
234 |                 ]
235 |             ]
236 |         ]);
237 | 
238 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
239 |         $this->assertTrue(Auth::hasAnyRole('myapp-backend', ['myapp-backend-role1', 'myapp-backend-role3']));
240 |     }
241 | 
242 |     public function test_check_user_no_has_any_role_in_resource()
243 |     {
244 |         $this->buildCustomToken([
245 |             'resource_access' => [
246 |                 'myapp-backend' => [
247 |                     'roles' => [
248 |                         'myapp-backend-role1',
249 |                         'myapp-backend-role2'
250 |                     ]
251 |                 ],
252 |                 'myapp-frontend' => [
253 |                     'roles' => [
254 |                         'myapp-frontend-role1',
255 |                         'myapp-frontend-role2'
256 |                     ]
257 |                 ]
258 |             ]
259 |         ]);
260 | 
261 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
262 |         $this->assertFalse(Auth::hasAnyRole('myapp-backend', ['myapp-backend-role3', 'myapp-backend-role4']));
263 |     }
264 | 
265 |     public function test_prevent_cross_roles_resources_with_any_role()
266 |     {
267 |         $this->buildCustomToken([
268 |             'resource_access' => [
269 |                 'myapp-backend' => [
270 |                     'roles' => [
271 |                         'myapp-backend-role1',
272 |                         'myapp-backend-role2'
273 |                     ]
274 |                 ],
275 |                 'myapp-frontend' => [
276 |                     'roles' => [
277 |                         'myapp-frontend-role1',
278 |                         'myapp-frontend-role2'
279 |                     ]
280 |                 ]
281 |             ]
282 |         ]);
283 | 
284 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
285 |         $this->assertFalse(Auth::hasAnyRole('myapp-backend', ['myapp-frontend-role1', 'myapp-frontend-role2']));
286 |     }
287 | 
288 |     public function test_check_user_has_scope()
289 |     {
290 |         $this->buildCustomToken([
291 |             'scope' => 'scope-a scope-b scope-c',
292 |         ]);
293 | 
294 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
295 |         $this->assertTrue(Auth::hasScope('scope-a'));
296 |     }
297 | 
298 |     public function test_check_user_no_has_scope()
299 |     {
300 |         $this->buildCustomToken([
301 |             'scope' => 'scope-a scope-b scope-c',
302 |         ]);
303 | 
304 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
305 |         $this->assertFalse(Auth::hasScope('scope-d'));
306 |     }
307 | 
308 |     public function test_check_user_has_any_scope()
309 |     {
310 |         $this->buildCustomToken([
311 |             'scope' => 'scope-a scope-b scope-c',
312 |         ]);
313 | 
314 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
315 |         $this->assertTrue(Auth::hasAnyScope(['scope-a', 'scope-c']));
316 |     }
317 | 
318 |     public function test_check_user_no_has_any_scope()
319 |     {
320 |         $this->buildCustomToken([
321 |             'scope' => 'scope-a scope-b scope-c',
322 |         ]);
323 | 
324 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
325 |         $this->assertFalse(Auth::hasAnyScope(['scope-f', 'scope-k']));
326 |     }
327 | 
328 |     public function test_check_user_scopes()
329 |     {
330 |         $this->buildCustomToken([
331 |             'scope' => 'scope-a scope-b scope-c',
332 |         ]);
333 | 
334 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
335 | 
336 |         $expectedValues = ["scope-a", "scope-b", "scope-c"];
337 |         foreach ($expectedValues as $value) {
338 |             $this->assertContains($value, Auth::scopes());
339 |         }
340 |         $this->assertCount(count($expectedValues), Auth::scopes());
341 |     }
342 | 
343 |     public function test_check_user_no_scopes()
344 |     {
345 |         $this->buildCustomToken([
346 |             'scope' => null,
347 |         ]);
348 | 
349 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
350 |         $this->assertCount(0, Auth::scopes());
351 |     }
352 | 
353 |     public function test_custom_user_retrieve_method()
354 |     {
355 |         config(['keycloak.user_provider_custom_retrieve_method' => 'custom_retrieve']);
356 | 
357 |         Auth::extend('keycloak', function ($app, $name, array $config) {
358 |             return new KeycloakGuard(new CustomUserProvider(new BcryptHasher(), User::class), $app->request);
359 |         });
360 | 
361 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
362 |         $this->assertTrue(Auth::user()->customRetrieve);
363 |     }
364 | 
365 |     public function test_throws_a_exception_with_invalid_iat()
366 |     {
367 |         $this->expectException(TokenException::class);
368 | 
369 |         $this->buildCustomToken([
370 |             'iat' => time() + 30,   // time ahead in the future
371 |             'preferred_username' => 'johndoe',
372 |             'resource_access' => ['myapp-backend' => []]
373 |         ]);
374 | 
375 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
376 |     }
377 | 
378 |     public function test_works_with_leeway()
379 |     {
380 |         // Allows up to 60 seconds ahead in the  future
381 |         config(['keycloak.leeway' => 60]);
382 | 
383 |         $this->buildCustomToken([
384 |             'iat' => time() + 30, // time ahead in the future
385 |             'preferred_username' => 'johndoe',
386 |             'resource_access' => ['myapp-backend' => []]
387 |         ]);
388 | 
389 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
390 |         $this->assertEquals($this->user->username, Auth::user()->username);
391 |     }
392 | 
393 |     public function test_authenticates_with_custom_input_key()
394 |     {
395 |         config(['keycloak.input_key' => "api_token"]);
396 | 
397 |         $this->json('GET', '/foo/secret?api_token=' . $this->token);
398 | 
399 |         $this->assertEquals(Auth::id(), $this->user->id);
400 | 
401 |         $this->json('POST', '/foo/secret', ['api_token' => $this->token]);
402 |     }
403 | 
404 |     public function test_authentication_prefers_bearer_token_over_with_custom_input_key()
405 |     {
406 |         config(['keycloak.input_key' => "api_token"]);
407 | 
408 |         $this->withKeycloakToken()->json('GET', '/foo/secret?api_token=some-junk');
409 | 
410 |         $this->assertEquals(Auth::id(), $this->user->id);
411 | 
412 |         $this->json('POST', '/foo/secret', ['api_token' => $this->token]);
413 |     }
414 | 
415 |     public function test_acting_as_keycloak_user_trait()
416 |     {
417 |         $this->actingAsKeycloakUser($this->user)->json('GET', '/foo/secret');
418 | 
419 |         $this->assertEquals($this->user->username, Auth::user()->username);
420 |         $token = Token::decode(request()->bearerToken(), config('keycloak.realm_public_key'), config('keycloak.leeway'), config('keycloak.token_encryption_algorithm'));
421 |         $this->assertNotNull($token->iat);
422 |         $this->assertNotNull($token->exp);
423 |         $this->assertNotNull($token->iss);
424 |         $this->assertNotNull($token->azp);
425 |         $this->assertNotNull($token->aud);
426 |     }
427 | 
428 |     public function test_acting_as_keycloak_user_trait_with_username()
429 |     {
430 |         $this->actingAsKeycloakUser($this->user->username)->json('GET', '/foo/secret');
431 | 
432 |         $this->assertEquals($this->user->username, Auth::user()->username);
433 |         $token = Token::decode(request()->bearerToken(), config('keycloak.realm_public_key'), config('keycloak.leeway'), config('keycloak.token_encryption_algorithm'));
434 |         $this->assertNotNull($token->iat);
435 |         $this->assertNotNull($token->exp);
436 |     }
437 | 
438 |     /**
439 |      * @dataProvider scopeProvider
440 |      *
441 |      * @return void
442 |      */
443 |     public function test_acting_as_keycloak_user_trait_with_custom_payload(string $scope)
444 |     {
445 |         UserFactory::new()->create([
446 |             'username' => 'test_username',
447 |         ]);
448 |         $payload = [
449 |             'sub' => 'test_sub',
450 |             'aud' => 'test_aud',
451 |             'preferred_username' => 'test_username',
452 |             'iat' => 12345,
453 |             'exp' => 9999999999999,
454 |         ];
455 | 
456 |         $arg = [];
457 | 
458 |         if ($scope === 'class') {
459 |             $this->jwtPayload = $payload;
460 |         } else {
461 |             $this->jwtPayload['sub'] = 'should_be_overwritten';
462 |             $arg = $payload;
463 |         }
464 | 
465 |         $this->actingAsKeycloakUser(payload: $arg)->json('GET', '/foo/secret');
466 | 
467 |         $this->assertEquals('test_username', Auth::user()->username);
468 |         $token = Token::decode(request()->bearerToken(), config('keycloak.realm_public_key'), config('keycloak.leeway'), config('keycloak.token_encryption_algorithm'));
469 |         $this->assertEquals(12345, $token->iat);
470 |         $this->assertEquals(9999999999999, $token->exp);
471 |         $this->assertEquals('test_sub', $token->sub);
472 |         $this->assertEquals('test_aud', $token->aud);
473 |         $this->assertTrue(config('keycloak.load_user_from_database'));
474 |     }
475 | 
476 |     public function test_acting_as_keycloak_user_trait_without_user()
477 |     {
478 |         $this->actingAsKeycloakUser()->json('GET', '/foo/secret');
479 | 
480 |         $this->assertTrue(Auth::hasUser());
481 | 
482 |         $this->assertFalse(Auth::guest());
483 |     }
484 | 
485 |     public function test_it_decodes_token_with_the_configured_encryption_algorithm()
486 |     {
487 |         $this->prepareCredentials('ES256', [
488 |             'private_key_type' => OPENSSL_KEYTYPE_EC,
489 |             'curve_name' => 'prime256v1'
490 |         ]);
491 | 
492 |         config([
493 |             'keycloak.token_encryption_algorithm' => 'ES256',
494 |             'keycloak.realm_public_key' => Token::plainPublicKey($this->publicKey)
495 |         ]);
496 | 
497 |         $this->withKeycloakToken()->json('GET', '/foo/secret');
498 |         $this->assertEquals($this->user->username, Auth::user()->username);
499 |     }
500 | 
501 |     public function scopeProvider(): array
502 |     {
503 |         return [
504 |             ['local'],
505 |             ['class'],
506 |         ];
507 |     }
508 | }
509 | 


--------------------------------------------------------------------------------