Simple Keycloak Guard for Laravel

https://github.com/robsontenorio/laravel-keycloak-guard
Admin
This package enables authentication of users on a Laravel API using JWT tokens generated by a...
Tokens:36,147
Snippets:295
Trust Score:9.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: check / guest

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to use the check() and guest() methods with the 'api' guard to verify authentication status.

```php
if (Auth::guard('api')->check()) {
    echo 'Authenticated as ' . Auth::guard('api')->user()->name;
}

if (Auth::guard('api')->guest()) {
    echo 'No authenticated user';
}
```

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

### Install package with Composer

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Run this command to require the laravel-keycloak-guard package via Composer.

```bash
composer require robsontenorio/laravel-keycloak-guard
```

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

### Example: getting the raw token

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/ActingAsKeycloakUser.md

Shows how to generate a token and use it in an HTTP test. The token is passed in the Authorization header as a Bearer token. The example asserts a successful response from the endpoint.

```php
use KeycloakGuard\ActingAsKeycloakUser;

class ApiTest extends TestCase
{
    use ActingAsKeycloakUser;

    public function test_exposes_raw_token()
    {
        $jwt = $this->generateKeycloakToken($this->user, ['aud' => 'account']);

        $response = $this->withHeader('Authorization', 'Bearer '.$jwt)
            ->getJson('/api/somewhere');

        $response->assertOk();
    }
}
```

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

### Run tests and code coverage

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Commands to install dependencies, run tests, and generate code coverage inside the package folder.

```shell
# Enter in package folder
cd /path/to/packages/laravel-keycloak-guard

# Install dependencies
composer install

# Run tests
composer test

# Code coverage
composer test:coverage
```

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

### Require the package from local repo

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Installs the package using the local repository with the @dev stability flag.

```shell
composer require robsontenorio/laravel-keycloak-guard:@dev
```

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

### Credentials array example with defaults

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/types.md

Example of the credentials array when using default configuration (`username` / `preferred_username`).

```php
['username' => 'johndoe']
```

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

### Example: bearer token

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to retrieve the token when the request includes an Authorization: Bearer header.

```php
// Request with header: Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
$token = Auth::guard('api')->getTokenForRequest();
```

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

### Configure input_key in keycloak.php

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Sets a custom request parameter to read the token when no Bearer token is present. The example shows GET and POST requests using the api_token parameter.

```php
// 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"])
```

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

### plainPublicKey() usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Shows converting a PEM key to plain format, storing it in config, and using it with Token::decode().

```php
use KeycloakGuard\Token;

$pem = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----";

$plain = Token::plainPublicKey($pem);
// "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

// Store it and use it later
config(['keycloak.realm_public_key' => $plain]);
Token::decode($jwt, $plain); // buildPublicKey() re-wraps it
```

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

### Protect routes with auth:api middleware

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Example routes in routes/api.php: public endpoint and protected group using 'auth:api' middleware.

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

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

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

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

### Direct construction example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to manually instantiate KeycloakGuard, mimicking what Auth::guard('api') does internally when the driver is 'keycloak'. The user() method returns the authenticated user or null.

```php
use Illuminate\Support\Facades\Auth;
use KeycloakGuard\KeycloakGuard;

// What Auth::guard('api') does internally when the driver is 'keycloak'
$guard = new KeycloakGuard(
    Auth::createUserProvider('users'),
    request()
);

$user = $guard->user(); // authenticated user, or null
```

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

### Example .env configuration

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Environment variables for Keycloak integration. KEYCLOAK_REALM_PUBLIC_KEY is required; KEYCLOAK_LOAD_USER_FROM_DATABASE=false uses JWT user; KEYCLOAK_APPEND_DECODED_TOKEN=true appends token info; KEYCLOAK_ALLOWED_RESOURCES=my-api requires that resource in token; KEYCLOAK_LEEWAY=60 optional for timestamp issues.

```dotenv
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.
```

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

### Example: setUser()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Sets a user instance on the 'api' guard. The user model is imported from the test namespace; in practice, use your own User model.

```php
use KeycloakGuard\Tests\Models\User; // your own User model in practice

Auth::guard('api')->setUser(new User(['username' => 'johndoe']));
Auth::guard('api')->user(); // the user just set
```

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

### Basic usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/ActingAsKeycloakUser.md

Example test class using the trait to authenticate a user and hit a protected route.

```php
use KeycloakGuard\ActingAsKeycloakUser;

class ProtectedRouteTest extends TestCase
{
    use ActingAsKeycloakUser;

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

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

### token() usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to retrieve and decode the JWT token payload. The decoded array contains claims like preferred_username, resource_access, and scope.

```php
$tokens = json_decode(Auth::guard('api')->token(), true);

// array:3 [
//   "preferred_username" => "johndoe",
//   "resource_access" => [...],
//   "scope" => "scope-a scope-b"
// ]
```

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

### hasAnyScope() example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows usage of `Auth::guard('api')->hasAnyScope()` with various scope lists, returning `true` when any scope matches and `false` when none do.

```php
// scopes(): ["scope-a", "scope-b", "scope-c"]
Auth::guard('api')->hasAnyScope(['scope-a', 'scope-c']); // true
Auth::guard('api')->hasAnyScope(['scope-a', 'scope-d']); // true
Auth::guard('api')->hasAnyScope(['scope-f', 'scope-k']); // false
```

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

### scopes()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Gets all user scopes.

```APIDOC
## scopes()

### Description
Gets all user scopes.

### Method
scopes()

### Parameters
None

### Returns
Array of scopes.

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

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

### Example decoded payload for resource_access roles

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Shows the structure of the decoded JWT payload with resource_access roles, used by hasRole and hasAnyRole methods.

```php
// Example decoded payload

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

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

### Get all user scopes with scopes()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Returns an array of all user scopes from the token payload.

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

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

### Example: custom input key fallback

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Demonstrates using a custom input key 'api_token' as fallback when no bearer token is present. The token is taken from the query parameter or POST body.

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

// GET /foo/secret?api_token=eyJhbGciOiJSUzI1NiIs...
$token = Auth::guard('api')->getTokenForRequest(); // falls back to query param
```

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

### Basic decode example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Decodes the bearer token from the request using configuration values. Outputs the preferred_username claim, e.g., "johndoe".

```php
use KeycloakGuard\Token;

$payload = Token::decode(
    request()->bearerToken(),
    config('keycloak.realm_public_key'),
    config('keycloak.leeway'),
    config('keycloak.token_encryption_algorithm'),
);

echo $payload->preferred_username; // "johndoe"
```

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

### validate() no database example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

When load_user_from_database is false, the user is a fresh instance of the provider model with no attributes. The token principal itself acts as the user.

```php
// config/keycloak.php
'load_user_from_database' => false,

$user = Auth::guard('api')->user();
// $user is a fresh instance of the provider model with no attributes
echo count($user->getAttributes()); // 0
```

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

### hasScope() example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows usage of `Auth::guard('api')->hasScope()` with a scope that exists and one that does not, returning `true` and `false` respectively.

```php
Auth::guard('api')->hasScope('scope-a'); // true
Auth::guard('api')->hasScope('scope-d'); // false
```

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

### scopes() example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows the output of `Auth::guard('api')->scopes()` for a token payload with scope "scope-a scope-b scope-c". The method returns an array of the individual scopes.

```php
// token payload: { "scope": "scope-a scope-b scope-c" }
Auth::guard('api')->scopes();
// [
//   0 => "scope-a",
//   1 => "scope-b",
//   2 => "scope-c",
// ]
```

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

### Custom payload and no database example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/ActingAsKeycloakUser.md

Example test method with custom claims and no user, disabling database lookup.

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

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

### id() usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to retrieve the authenticated user's ID via the 'api' guard. The result is an integer or string UUID depending on the user model.

```php
$id = Auth::guard('api')->id(); // e.g. 42 or "550e8400-e29b-41d4-a716-446655440000"
```

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

### Example decoded payload for scopes

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Shows the structure of the decoded JWT payload with a scope string, used by scopes(), hasScope(), and hasAnyScope().

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

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

### Example .env for Keycloak Guard

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/configuration.md

Environment variables for the Keycloak guard. KEYCLOAK_REALM_PUBLIC_KEY is required; KEYCLOAK_LOAD_USER_FROM_DATABASE=false is used when there is no users table; KEYCLOAK_APPEND_DECODED_TOKEN=true attaches $user->token; KEYCLOAK_ALLOWED_RESOURCES restricts allowed resources; KEYCLOAK_LEEWAY sets seconds of leeway.

```env
KEYCLOAK_REALM_PUBLIC_KEY=MIIBIj...
KEYCLOAK_LOAD_USER_FROM_DATABASE=false
KEYCLOAK_APPEND_DECODED_TOKEN=true
KEYCLOAK_ALLOWED_RESOURCES=my-api
KEYCLOAK_LEEWAY=60
```

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

### Error handling example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Shows how to catch specific Firebase JWT exceptions for expired, signature-invalid, and other unexpected value errors. Also demonstrates that a null token returns null without throwing.

```php
use Firebase\JWT\ExpiredException;
use Firebase\JWT\SignatureInvalidException;
use KeycloakGuard\Token;

try {
    $payload = Token::decode($rawToken, config('keycloak.realm_public_key'), 60);
} catch (ExpiredException $e) {
    // token past its exp claim
} catch (SignatureInvalidException $e) {
    // wrong public key / tampered token
} catch (\UnexpectedValueException $e) {
    // before-valid, structural errors, algorithm mismatch
}

// null token → null, no exception
$payload = Token::decode(null, config('keycloak.realm_public_key')); // null
```

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

### hasRole() usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to use hasRole() with the 'api' guard. The token payload must contain resource_access with the resource and its roles array. Returns true for matching role, false for cross-resource roles.

```php
// token payload:
// 'resource_access' => [
//   'myapp-backend' => ['roles' => ['myapp-backend-role1']],
// ],

Auth::guard('api')->hasRole('myapp-backend', 'myapp-backend-role1'); // true
Auth::guard('api')->hasRole('myapp-backend', 'myapp-frontend-role1'); // false (cross-resource roles never match)

```

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

### resource_access structure example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/types.md

Shows the expected structure of the `resource_access` object inside the decoded token. Verified by `validateResources()` and queried by role-check methods. Each resource key maps to an object with a `roles` array.

```php
$token->resource_access = (object) [
    'myapp-backend' => (object) [
        'roles' => ['myapp-backend-role1', 'myapp-backend-role2'],
    ],
    'myapp-frontend' => (object) [
        'roles' => ['myapp-frontend-role1', 'myapp-frontend-role2'],
    ],
];
```

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

### hasAnyRole() usage example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to use hasAnyRole() with the 'api' guard. Returns true if any of the listed roles is present in the resource's roles array, false if none match.

```php
Auth::guard('api')->hasAnyRole('myapp-backend', ['myapp-backend-role1', 'myapp-backend-role3']); // true if role1 is present
Auth::guard('api')->hasAnyRole('myapp-backend', ['myapp-frontend-role1', 'myapp-frontend-role2']); // false

```

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

### Catching KeycloakGuardException

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Example of catching any package exception when calling Auth::guard('api')->user(). The caught exception's message is prefixed with '[Keycloak Guard] '.

```php
use KeycloakGuard\Exceptions\KeycloakGuardException;

try {
    $user = Auth::guard('api')->user();
} catch (KeycloakGuardException $e) {
    // "[Keycloak Guard] Expired token"
    report($e->getMessage());
}
```

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

### validate() default database lookup example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Configures KeycloakGuard to load users from the database using the 'username' credential and 'preferred_username' token attribute. Auth::guard('api') triggers validate with the username from the decoded token.

```php
// config/keycloak.php
'load_user_from_database' => true,
'user_provider_credential' => 'username',
'token_principal_attribute' => 'preferred_username',

// Auth::guard('api') triggers validate(['username' => $decodedToken->preferred_username])
$user = Auth::guard('api')->user();
```

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

### Example: reading the appended token

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Shows how to access the decoded JWT payload via $user->token when keycloak.append_decoded_token is enabled. The config file sets the flag to true, then the user's token is used to read resource_access roles/groups.

```php
// config/keycloak.php
'append_decoded_token' => true,

$user = Auth::guard('api')->user();
$roles = $user->token->resource_access; // roles/groups from the JWT
```

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

### validate() custom user provider retrieve method example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Configures a custom retrieve method on the user provider. The custom method receives the full decoded token object and the credentials array.

```php
// config/keycloak.php
'load_user_from_database' => true,
'user_provider_custom_retrieve_method' => 'custom_retrieve',

// app/Providers/AppServiceProvider.php
// Custom provider method signature:
// public function custom_retrieve(object $token, array $credentials)

Auth::guard('api')->user(); // provider::custom_retrieve($decodedToken, $credentials) is called
```

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

### Catching TokenException

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Example of catching TokenException when using Auth::guard('api')->user(). The exception message includes the '[Keycloak Guard] ' prefix, e.g., '[Keycloak Guard] Expired token'. For 'Cannot handle token prior to <DATE>', raise keycloak.leeway (e.g., 60 seconds) to absorb clock skew.

```php
use KeycloakGuard\Exceptions\TokenException;

try {
    Auth::guard('api')->user();
} catch (TokenException $e) {
    abort(401, $e->getMessage()); // e.g. "[Keycloak Guard] Expired token"
}
```

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

### Get full decoded JWT token with Auth::token()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Returns the full decoded JWT token from the authenticated user. Can be called via Auth::token() or Auth::user()->token().

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

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

### boot() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Defines the boot() method with void return type.

```php
public function boot(): void
```

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

### Reuse payload via class property example

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/ActingAsKeycloakUser.md

Example test class reusing payload claims via a class property. Note: the trait reads `$this->jwtPayload`, but the example uses `$tokenPayload`.

```php
use KeycloakGuard\ActingAsKeycloakUser;

class AdminTest extends TestCase
{
    use ActingAsKeycloakUser;

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

    public function test_one()
    {
        $this->actingAsKeycloakUser($this->user)->getJson('/api/a')->assertOk();
    }
}
```

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

### buildPublicKey() implementation

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Wraps a plain public key string into PEM format by word-wrapping at 64 characters. This allows decode() to accept both plain and PEM-formatted keys.

```php
return "-----BEGIN PUBLIC KEY-----\n".wordwrap($key, 64, "\n", true)."\n-----END PUBLIC KEY-----";
```

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

### Register service provider for Lumen

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

For Lumen, register the KeycloakGuardServiceProvider in bootstrap/app.php. Also uncomment $app->withFacades(); for facades.

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

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

### buildPublicKey() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Declares the private static method buildPublicKey that wraps a plain key into PEM format.

```php
private static function buildPublicKey(string $key): string
```

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

### plainPublicKey() implementation

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Removes PEM header/footer and trims whitespace, also removes literal backslash-n sequences. Returns a single-line base64 string for .env storage.

```php
$string = str_replace('-----BEGIN PUBLIC KEY-----', '', $key);
$string = trim(str_replace('-----END PUBLIC KEY-----', '', $string));
$string = str_replace('\n', '', $string);

return $string;
```

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

### Clone the package repository

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Clones the laravel-keycloak-guard repository into the packages directory of your Laravel application.

```shell
git clone git@github.com:robsontenorio/laravel-keycloak-guard.git packages/laravel-keycloak-guard
```

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

### register() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Defines the register() method with void return type.

```php
public function register(): void
```

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

### Merge package config

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Merges the package config under the 'keycloak' key so config('keycloak.*') resolves.

```php
$this->mergeConfigFrom(__DIR__.'/../config/keycloak.php', 'keycloak');
```

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

### KeycloakGuard::__construct

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Creates a new KeycloakGuard instance. The constructor decodes and validates the token from the request and resolves the authenticated user.

```APIDOC
## Constructor

### Description
Creates a new KeycloakGuard instance. The constructor decodes and validates the token from the request and resolves the authenticated user.

### Method
Constructor

### Signature
```php
public function __construct(protected UserProvider $provider, protected Request $request)
```

### Parameters
- `$provider` (Illuminate\Contracts\Auth\UserProvider) - Required - User provider used to look up the authenticated user from the database
- `$request` (Illuminate\Http\Request) - Required - Current HTTP request; used to extract the bearer/input token

### Return
A fully authenticated guard instance — the token is decoded and the user resolved inside the constructor.

### Throws
- `KeycloakGuard\Exceptions\TokenException` — when the token cannot be decoded or validated
- `KeycloakGuard\Exceptions\UserNotFoundException` — when `load_user_from_database` is `true` and no user matches the credentials
- `KeycloakGuard\Exceptions\ResourceAccessNotAllowedException` — when `ignore_resources_validation` is `false` and the token's `resource_access` has no intersection with `allowed_resources`

### Example: direct construction
```php
use Illuminate\Support\Facades\Auth;
use KeycloakGuard\KeycloakGuard;

// What Auth::guard('api') does internally when the driver is 'keycloak'
$guard = new KeycloakGuard(
    Auth::createUserProvider('users'),
    request()
);

$user = $guard->user(); // authenticated user, or null
```

### Example: constructor failure (invalid token)
```php
use KeycloakGuard\Exceptions\TokenException;

try {
    $guard = new KeycloakGuard(Auth::createUserProvider('users'), request());
} catch (TokenException $e) {
    // e.g. "Expired token" — return 401
    abort(401, $e->getMessage());
}
```
```

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

### Import ServiceProvider

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Imports the AuthServiceProvider as ServiceProvider for the class declaration.

```php
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
```

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

### plainPublicKey() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Declares the static method plainPublicKey that accepts a PEM public key string and returns a single-line base64 string.

```php
public static function plainPublicKey(string $key): string
```

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

### Configure auth guard in config/auth.php

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Wires the 'keycloak' driver to the 'users' provider in the application's auth configuration.

```php
'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],
'guards' => [
    'api' => [
        'driver' => 'keycloak',
        'provider' => 'users',
    ],
],
```

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

### token()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Returns the full decoded JWT token from the authenticated user.

```APIDOC
## token()

### Description
Returns the full decoded JWT token from the authenticated user.

### Method
token()

### Parameters
None

### Returns
Decoded JWT token (array or object).

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

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

### guest() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Returns true when the current user is a guest (inverse of check()).

```php
public function guest(): bool
```

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

### check()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Determines if the current user is authenticated.

```APIDOC
## check()

### Description
Determines if the current user is authenticated.

### Method
check()

### Parameters
None

### Returns
Boolean - true if authenticated, false otherwise.
```

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

### Constructor signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Defines the KeycloakGuard constructor, which accepts a user provider and the current HTTP request. The token is decoded and the user resolved inside the constructor, so failures throw exceptions.

```php
public function __construct(protected UserProvider $provider, protected Request $request)
```

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

### setUser()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Sets the current user.

```APIDOC
## setUser()

### Description
Sets the current user.

### Method
setUser()

### Parameters
- user (mixed) - Required - The user to set.

### Returns
void
```

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

### Class declaration

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Declares the service provider class extending ServiceProvider.

```php
class KeycloakGuardServiceProvider extends ServiceProvider
```

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

### validate()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Validates the token and loads the user. Always returns true when it completes. Throws exceptions on resource access failure or user not found.

```APIDOC
## validate()

### Description
Validates the token and loads the user. Always returns `true` when it completes. Throws `ResourceAccessNotAllowedException` if the token's `resource_access` does not overlap `keycloak.allowed_resources` (unless `ignore_resources_validation` is `true`). Throws `UserNotFoundException` if no matching user is found in the database.

### Method
`validate(array $credentials = []): true`

### Parameters
#### Parameters
- **$credentials** (array) - Optional - Credentials passed to the user provider, of the form `['username' => 'johndoe']` (`user_provider_credential` => token claim for `token_principal_attribute`)

### Return Type
`true` (the method always returns `true` when it completes)

### Behavior
1. Calls the protected `validateResources()` — throws `ResourceAccessNotAllowedException` if the token's `resource_access` does not overlap `keycloak.allowed_resources` (unless `ignore_resources_validation` is `true`).
2. If `keycloak.load_user_from_database` is `true`:
   - If `keycloak.user_provider_custom_retrieve_method` is set, calls `$this->provider->{$methodOnProvider}($this->decodedToken, $credentials)` — the custom method receives the full decoded token object and the credentials array.
   - Otherwise calls `$this->provider->retrieveByCredentials($credentials)`.
   - If no user is returned, throws `UserNotFoundException` with the message `User not found. Credentials: <json_encode($credentials)>`.
3. If `keycloak.load_user_from_database` is `false`: instantiates a bare model from `$this->provider->getModel()` (`new $class`) with no attributes — the "user" is the token principal itself.
4. Calls `setUser()` and returns `true`.

### Throws
- `ResourceAccessNotAllowedException` — resource check failure.
- `UserNotFoundException` — no matching user in database.

### Example: default database lookup
```php
// config/keycloak.php
'load_user_from_database' => true,
'user_provider_credential' => 'username',
'token_principal_attribute' => 'preferred_username',

// Auth::guard('api') triggers validate(['username' => $decodedToken->preferred_username])
$user = Auth::guard('api')->user();
```

### Example: custom user provider retrieve method
```php
// config/keycloak.php
'load_user_from_database' => true,
'user_provider_custom_retrieve_method' => 'custom_retrieve',

// app/Providers/AppServiceProvider.php
// Custom provider method signature:
// public function custom_retrieve(object $token, array $credentials)

Auth::guard('api')->user(); // provider::custom_retrieve($decodedToken, $credentials) is called
```

### Example: no database
```php
// config/keycloak.php
'load_user_from_database' => false,

$user = Auth::guard('api')->user();
// $user is a fresh instance of the provider model with no attributes
echo count($user->getAttributes()); // 0
```
```

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

### Publish config file

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Publishes config/keycloak.php to the application's config directory under the 'config' tag.

```php
$this->publishes([__DIR__.'/../config/keycloak.php' => config_path('keycloak.php')], 'config');
```

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

### guest()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Determines if the current user is a guest (not authenticated).

```APIDOC
## guest()

### Description
Determines if the current user is a guest (not authenticated).

### Method
guest()

### Parameters
None

### Returns
Boolean - true if guest, false otherwise.
```

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

### TokenException class definition

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Defines the TokenException class extending KeycloakGuardException. Used to signal token decoding failures in the Keycloak guard.

```php
class TokenException extends KeycloakGuardException {}
```

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

### Act as Keycloak user in tests with actingAsKeycloakUser()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Uses the KeycloakGuard\ActingAsKeycloakUser trait to act as a user and skip Keycloak auth in tests. Requires setting keycloak.preferred_username if not using keycloak.load_user_from_database.

```php
use KeycloakGuard\ActingAsKeycloakUser;

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

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

### Check any roles with Auth::hasAnyRole()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Checks if the authenticated user has any of the given roles in resource_access. Returns true if at least one role matches.

```php
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
```

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

### Composer auto-discovery configuration

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Registers the service provider for Laravel auto-discovery via the extra.laravel.providers entry in composer.json.

```json
"extra": {
    "laravel": {
        "providers": [
            "KeycloakGuard\\KeycloakGuardServiceProvider"
        ]
    }
}
```

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

### guest()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Returns true when the current user is a guest (inverse of check()).

```APIDOC
## guest()

### Description
Returns `true` when the current user is a guest (inverse of `check()`).

### Method
`guest()`

### Signature
```php
public function guest(): bool
```

### Returns
- **bool** - `true` if the user is a guest, `false` otherwise.

### Example
```php
if (Auth::guard('api')->guest()) {
    echo 'No authenticated user';
}
```
```

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

### Publish Keycloak config file with artisan vendor:publish

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/configuration.md

Run this artisan command to publish the package configuration file to config/keycloak.php. The package works without publishing because values are merged via KeycloakGuardServiceProvider::boot() → mergeConfigFrom.

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

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

### Add local repository to composer.json

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Configures Composer to use the local path repository for the package during development.

```shell
composer config repositories.local '{"type": "path", "url": "/path/to/packages/laravel-keycloak-guard"}'  
```

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

### Token::plainPublicKey()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Static method that converts a PEM public key string into a single-line base64 string by removing PEM header/footer and trimming whitespace. Useful for storing the key in environment variables.

```APIDOC
## Token::plainPublicKey()

### Description
Converts a PEM public key string into a single-line base64 string by removing the PEM header/footer and trimming whitespace. The result is suitable for storage in `.env` as `KEYCLOAK_REALM_PUBLIC_KEY`.

### Method
`public static function plainPublicKey(string $key): string`

### Parameters
- `$key` (string) - Required - PEM public key string, possibly multi-line with `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` fences.

### Return Type
`string` - The key with PEM header/footer removed and all whitespace/newlines trimmed.

### Example
```php
use KeycloakGuard\Token;

$pem = "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----";

$plain = Token::plainPublicKey($pem);
// "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

// Store it and use it later
config(['keycloak.realm_public_key' => $plain]);
Token::decode($jwt, $plain); // buildPublicKey() re-wraps it
```
```

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

### user()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Retrieves the currently authenticated user.

```APIDOC
## user()

### Description
Retrieves the currently authenticated user.

### Method
user()

### Parameters
None

### Returns
The authenticated user instance or null.
```

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

### Check any scopes with Auth::hasAnyScope()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Checks if the authenticated user has any of the given scopes. Returns true if at least one scope matches.

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

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

### actingAsKeycloakUser()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Acts as a Keycloak user in tests, skipping Keycloak authentication.

```APIDOC
## actingAsKeycloakUser()

### Description
Acts as a Keycloak user in tests, skipping Keycloak authentication. Can be used with optional user and payload arguments.

### Method
actingAsKeycloakUser(user = null, payload = [])

### Parameters
- user (mixed) - Optional - A string identifier or Eloquent model. If not provided, uses the default user.
- payload (array) - Optional - Token payload overrides. Default claims include 'aud', 'iat', 'exp', 'iss', 'azp', 'resource_access', and either 'sub' or 'preferred_username' depending on config.

### Returns
$this (for chaining)

### Example
```php
use KeycloakGuard\ActingAsKeycloakUser;

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

### Notes
- If not using `keycloak.load_user_from_database`, set `keycloak.preferred_username` with a valid `preferred_username` for tests.
- Payload can be provided as a class property `$tokenPayload` to reuse across tests.
- Priority: argument payload overrides class property; `$user` argument has highest priority over the claim referred in `token_principal_attribute` config.
```

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

### Constructor failure handling (invalid token)

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Catches TokenException when constructing the guard with an invalid token. The exception message, e.g. 'Expired token', can be used to return a 401 response.

```php
use KeycloakGuard\Exceptions\TokenException;

try {
    $guard = new KeycloakGuard(Auth::createUserProvider('users'), request());
} catch (TokenException $e) {
    // e.g. "Expired token" — return 401
    abort(401, $e->getMessage());
}
```

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

### hasAnyScope(['scope-a', 'scope-c'])

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Checks if the authenticated user has any of the given scopes.

```APIDOC
## hasAnyScope(['scope-a', 'scope-c'])

### Description
Checks if the authenticated user has any of the given scopes.

### Method
hasAnyScope(scopes)

### Parameters
- scopes (array) - Required - Array of scope names.

### Returns
Boolean - true if the user has any of the scopes, false otherwise.

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

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

### Exception hierarchy diagram

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Shows the inheritance tree of package exceptions, all extending KeycloakGuardException which extends PHP's UnexpectedValueException.

```text
Exception
└── UnexpectedValueException                      (PHP SPL)
    └── KeycloakGuardException                   (src/Exceptions/KeycloakGuardException.php)
        ├── TokenException                      (src/Exceptions/TokenException.php)
        ├── UserNotFoundException                (src/Exceptions/UserNotFoundException.php)
        └── ResourceAccessNotAllowedException    (src/Exceptions/ResourceAccessNotAllowedException.php)
```

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

### hasAnyRole('some-resource', ['some-role1', 'some-role2'])

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Checks if the authenticated user has any of the given roles on a resource.

```APIDOC
## hasAnyRole('some-resource', ['some-role1', 'some-role2'])

### Description
Checks if the authenticated user has any of the given roles on a resource.

### Method
hasAnyRole(resource, roles)

### Parameters
- resource (string) - Required - The resource name.
- roles (array) - Required - Array of role names.

### Returns
Boolean - true if the user has any of the roles, false otherwise.

### Example
```php
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
```
```

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

### Protect routes with auth:api middleware

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuardServiceProvider.md

Protects routes with the auth:api middleware, triggering KeycloakGuard construction on each request.

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

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

### validate()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Validates the given credentials.

```APIDOC
## validate()

### Description
Validates the given credentials.

### Method
validate()

### Parameters
- credentials (array) - Required - The credentials to validate.

### Returns
Boolean - true if valid, false otherwise.
```

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

### Token::decode() implementation

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/Token.md

Internal implementation of decode(): sets the JWT leeway, builds the public key, and decodes the token. Returns null if the token is null.

```php
JWT::$leeway = $leeway;
$publicKey = self::buildPublicKey($publicKey);

return $token ? JWT::decode($token, new Key($publicKey, $algorithm)) : null;
```

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

### check() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Declares the method that returns true when the current user is authenticated, false otherwise. A TokenException is thrown during construction if the token is invalid.

```php
public function check(): bool
```

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

### KeycloakGuardException class definition

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Base exception class for all package errors. Prefixes every message with '[Keycloak Guard] '. Never thrown directly; catch this to handle all package exceptions.

```php
class KeycloakGuardException extends UnexpectedValueException
{
    public function __construct(string $message)
    {
        parent::__construct("[Keycloak Guard] {$message}");
    }
}
```

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

### hasAnyRole() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Method signature for checking if any of the given roles exist in the resource's roles array. Returns true if at least one matches, false otherwise (including when resource or roles key is absent).

```php
public function hasAnyRole(string $resource, array $roles): bool

```

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

### scopes() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Returns all user scopes as an array of strings, split from the space-separated `scope` claim of the decoded token. Returns an empty array `[]` when the `scope` claim is absent or falsy.

```php
public function scopes(): array
```

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

### token()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Returns the full decoded JWT token from the authenticated user as a JSON-encoded string. Returns false when json_encode fails or when no decoded token exists.

```APIDOC
## token()

### Description
Returns the full decoded JWT token from the authenticated user as a JSON-encoded string (`json_encode($this->decodedToken)`). Returns `false` when `json_encode` fails (e.g. invalid UTF-8 in claims) or when no decoded token exists (decoding `null`).

This is the documented alternative to `append_decoded_token`: even with that option off, the token payload remains reachable via `Auth::token()`.

### Method
`token()`

### Return Type
`false|string`

### Example
```php
$tokens = json_decode(Auth::guard('api')->token(), true);

// array:3 [
//   "preferred_username" => "johndoe",
//   "resource_access" => [...],
//   "scope" => "scope-a scope-b"
// ]
```
```

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

### config/keycloak.php - Full package configuration

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/configuration.md

Verbatim source of config/keycloak.php. All options map to environment variables; defaults include 'RS256' for token_encryption_algorithm, true for load_user_from_database, 'username' for user_provider_credential, and 'preferred_username' for token_principal_attribute. Note: when editing .env, ensure strings are trimmed.

```php
<?php

return [
    'realm_public_key' => env('KEYCLOAK_REALM_PUBLIC_KEY', null),

    'token_encryption_algorithm' => env('KEYCLOAK_TOKEN_ENCRYPTION_ALGORITHM', 'RS256'),

    'load_user_from_database' => env('KEYCLOAK_LOAD_USER_FROM_DATABASE', true),

    'user_provider_custom_retrieve_method' => env('KEYCLOAK_USER_PROVIDER_CUSTOM_RETRIEVE_METHOD', null),

    'user_provider_credential' => env('KEYCLOAK_USER_PROVIDER_CREDENTIAL', 'username'),

    'token_principal_attribute' => env('KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE', 'preferred_username'),

    'append_decoded_token' => env('KEYCLOAK_APPEND_DECODED_TOKEN', false),

    'allowed_resources' => env('KEYCLOAK_ALLOWED_RESOURCES', null),

    'ignore_resources_validation' => env('KEYCLOAK_IGNORE_RESOURCES_VALIDATION', false),

    'leeway' => env('KEYCLOAK_LEEWAY', 0),

    'input_key' => env('KEYCLOAK_TOKEN_INPUT_KEY', null),
];
```

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

### Remove local repository and re-require from Packagist

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Reverts to the Packagist version by unsetting the local repository and requiring the package again.

```shell
composer config --unset repositories.local
composer robsontenorio/laravel-keycloak-guard
```

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

### Throwing TokenException in authenticate()

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Shows how TokenException is thrown inside the protected authenticate() method when Token::decode() fails. Any \Exception from Token::decode() (e.g., from firebase/php-jwt) triggers this exception, preserving the original message with a '[Keycloak Guard] ' prefix.

```php
try {
    $this->decodedToken = Token::decode(/* ... */);
} catch (\Exception $e) {
    throw new TokenException($e->getMessage());
}
```

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

### ResourceAccessNotAllowedException class definition

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/errors.md

Defines the ResourceAccessNotAllowedException exception class, extending the base KeycloakGuardException. Thrown when the token lacks required resource access.

```php
class ResourceAccessNotAllowedException extends KeycloakGuardException {}
```

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

### token() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Returns the full decoded JWT token as a JSON-encoded string, or false when json_encode fails or no decoded token exists. This is the documented alternative to append_decoded_token.

```php
public function token(): false|string
```

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

### Act as Keycloak user with custom token payload

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/README.md

Passes a payload array to override default claims like aud, exp, iss. $user can be a string identifier or Eloquent model.

```php
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();
}
```

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

### getTokenForRequest() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Declares the method that extracts the raw JWT from the request. It has no parameters and returns a string.

```php
public function getTokenForRequest()
```

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

### validate() method signature

Source: https://github.com/robsontenorio/laravel-keycloak-guard/blob/master/_autodocs/api-reference/KeycloakGuard.md

Validates credentials and always returns true when it completes. Throws ResourceAccessNotAllowedException or UserNotFoundException on failure.

```php
public function validate(array $credentials = []): true
```
Tokens:
Raw