API authentication¶
Your SPA, mobile app or another service gets an access token from Keycloak and sends it as
Authorization: Bearer <token>. The package verifies the token offline against the realm's cached
public keys. A request needs no call to Keycloak and no database query, unless you
provision users.
There are two ways to plug it in. Both share the same validation, caching and user resolution.
Option 1: the keycloak.api middleware¶
// routes/api.php
Route::middleware('keycloak.api')->group(function () {
Route::get('/me', fn (Request $request) => $request->user());
Route::apiResource('orders', OrderController::class);
});
Route::middleware('keycloak.api:partners')->group(/* tokens of the "partners" guard */);
When nothing is passed it uses the api guard if you configured one, otherwise the default guard.
Failures return JSON:
With APP_DEBUG=true the response also contains a message with the exact reason (expired, wrong issuer,
audience...).
Option 2: the keycloak auth guard¶
Register a guard in config/auth.php:
'guards' => [
'web' => ['driver' => 'session', 'provider' => 'users'],
'api' => [
'driver' => 'keycloak',
'keycloak' => 'api', // which package guard (realm + client) to verify against
// 'provision' => false, // override provisioning for this guard
],
],
Then use Laravel's own auth middleware and helpers:
Route::middleware('auth:api')->get('/me', fn () => auth('api')->user());
auth('api')->check();
auth('api')->id(); // Keycloak subject (stateless) or local id
auth('api')->token(); // KeycloakToken
auth('api')->hasRole('admin');
auth('api')->validate(['token' => $jwt]); // check without logging in
Unauthenticated requests go through Laravel's normal AuthenticationException handling (JSON 401 for API
requests). The guard is safe for Laravel Octane: it is reset for every request.
Users: stateless or database¶
$request->user() is a Bhry98\KeycloakAuth\Auth\KeycloakUser built from the token claims. This is
the fastest option and fits microservices that don't own user data.
The local user (your users_model) is created on the first request and updated when the claims
change. While the claims stay the same, the write is skipped for provisioning.sync_ttl seconds, so a
hot request costs a single primary-key lookup. Existing rows with the same e-mail are adopted.
Map extra claims to columns with provisioning.attributes.
Service accounts (client-credentials tokens) are never written to the database. They always
resolve to a KeycloakUser, so machine clients work even with provisioning on.
Custom user resolution¶
Take full control over how a token becomes a user, for example to look up a tenant or deny unknown users:
// AppServiceProvider::boot()
use Bhry98\KeycloakAuth\Facades\Keycloak;
use Bhry98\KeycloakAuth\Token\KeycloakToken;
Keycloak::resolveUserUsing(function (KeycloakToken $token, string $guard) {
return User::firstWhere('keycloak_id', $token->subject()); // null = unauthenticated
});
Reading the token¶
use Bhry98\KeycloakAuth\Facades\Keycloak;
$token = Keycloak::token(); // current request token (or inject KeycloakToken)
$token->subject(); // user id
$token->email();
$token->username();
$token->azp(); // client the token was issued to
$token->roles(); // realm + guard-client roles
$token->scopes();
$token->groups();
$token->expiresAt(); // CarbonImmutable
$token->claim('tenant.id'); // any claim, dot notation
$token->jwt(); // raw token, e.g. to forward it
Validating tokens yourself¶
For queues, WebSockets, gRPC or anywhere outside HTTP middleware:
$token = Keycloak::validate($jwt, 'api'); // throws TokenValidationException
$token = Keycloak::check($jwt, 'api'); // or returns null
$token = Keycloak::decode($jwt); // claims only, NO verification
What is verified:
- Signature against the realm's JWKS, with only allow-listed algorithms.
- Expiry and not-before, with
token.leewayseconds of clock skew. - Issuer:
{base_url}/realms/{realm}or a configured public issuer. - Audience: when the guard has
audience, it must be inaudorazp. - Type:
typmust beBearer, so refresh and ID tokens are refused.
Performance notes¶
- Realm keys are cached in your cache store (
token.jwks_ttl, 1 day) and memoized in-process. - When a token is signed with an unknown key id (Keycloak rotated its keys), the keys are downloaded
again, at most once per
token.jwks_refresh_cooldownseconds. Forged tokens can't be used to flood Keycloak with requests. - The same token is verified only once per process (up to 256 recent tokens are memoized; the expiry is re-checked on every use).
- Use a shared cache (Redis) in production so every server and worker reuses the same keys and tokens.
Docker, Kubernetes and public URLs¶
Inside a cluster your app often reaches Keycloak at an internal URL (http://keycloak:8080), while tokens
are issued with the public URL as iss (https://sso.example.com/realms/my-realm). Keep the internal
URL for HTTP calls and trust the public issuer:
KEYCLOAK_BASE_URL=http://keycloak:8080
KEYCLOAK_ISSUER=https://sso.example.com # realm path is added automatically
You can also set issuer per guard (string or array) in the config.
Microservices¶
A typical setup: each service verifies incoming tokens with keycloak.api, and calls other services either
on behalf of the user (forward the token) or as itself (service account):
// forward the caller's token
Http::withKeycloakUserToken()->get('http://inventory/api/stock');
// call as this service (client credentials, cached until it expires)
Http::withKeycloakToken('api')->post('http://billing/api/invoices', $payload);
See OIDC & service tokens for token exchange and scopes.
Events¶
| Event | When |
|---|---|
TokenValidated |
a bearer token was accepted ($token, $guard) |
TokenValidationFailed |
a bearer token was rejected ($exception, $guard, $request), useful for auditing and alerts |
UserProvisioned |
the local user row was created or changed |