Authorization¶
All checks read the current request's token: the verified bearer token on API routes, or the session token on web routes. They make no network call, except UMA permissions.
Role semantics¶
| You write | Matches |
|---|---|
admin |
the realm role admin or the role admin of the guard's client (and of the token's azp) |
billing:invoice-viewer |
the role invoice-viewer of the client billing |
App\Enums\Role::Admin |
backed enums use their value, pure enums their name |
The "guard's client" can be changed with roles.clients or the guard's role_clients
(configuration).
Middleware¶
// at least one of the roles
Route::middleware(['keycloak.api', 'keycloak.role:admin,editor'])->group(/* ... */);
// all of the roles
Route::middleware(['keycloak.api', 'keycloak.roles:admin,auditor'])->group(/* ... */);
// client role
Route::middleware(['keycloak.api', 'keycloak.role:billing:invoice-viewer'])->get('/invoices', /* ... */);
// at least one of the scopes
Route::middleware(['keycloak.api', 'keycloak.scope:orders:read,orders:write'])->get('/orders', /* ... */);
// Keycloak Authorization Services (UMA), all listed permissions
Route::middleware(['keycloak.api', 'keycloak.permission:invoice#read'])->get('/invoices/{id}', /* ... */);
They work after keycloak.api, keycloak.web or auth:<keycloak guard>. Without a token they respond
with 401, without the role/scope with 403.
In code¶
use Bhry98\KeycloakAuth\Facades\Keycloak;
$token = Keycloak::token();
$token->hasRole('admin');
$token->hasAnyRole(['admin', 'editor']);
$token->hasAllRoles(['admin', 'auditor']);
$token->hasRealmRole('offline_access');
$token->hasClientRole('invoice-viewer', 'billing');
$token->realmRoles(); // ['admin', 'offline_access', ...]
$token->clientRoles(); // roles of the guard client(s)
$token->clientRoles('billing');
$token->allClientRoles(); // ['billing' => [...], 'account' => [...]]
$token->scopes(); // ['openid', 'email', 'orders:read']
$token->hasScope('orders:read');
$token->hasAnyScope(['a', 'b']);
$token->groups(); // ['/company/engineering']
$token->inGroup('engineering'); // matches "/company/engineering"
Gates and policies¶
The package registers these abilities (disable with 'gates' => false):
| Ability | Arguments |
|---|---|
keycloak-role |
one or more roles (any) |
keycloak-roles |
one or more roles (all) |
keycloak-scope |
one or more scopes (any) |
keycloak-group |
a group name or path |
Gate::allows('keycloak-role', 'admin');
Gate::authorize('keycloak-role', ['admin', 'editor']);
$this->authorize('keycloak-scope', 'orders:write'); // in a controller
can: middleware
Laravel's can:ability,arg middleware reads its arguments as route parameters or model classes, not
as plain strings. Use keycloak.role:... for routes, and the gates in code and Blade.
Inside your own policies, use the token directly:
public function update(User $user, Invoice $invoice): bool
{
return $user->hasRole('billing:invoice-editor') && $invoice->tenant_id === $user->tenant_id;
}
Blade directives¶
@keycloakRole('admin', 'editor')
<button>Publish</button>
@endkeycloakRole
@keycloakScope('orders:write')
<button>New order</button>
@endkeycloakScope
On the user model¶
Add HasKeycloakRoles to your user model (the bundled KCUserModel already has it):
use Bhry98\KeycloakAuth\Concerns\HasKeycloakRoles;
class User extends Authenticatable
{
use HasKeycloakRoles;
}
$user->hasRole('admin');
$user->hasAnyRole(['admin', 'editor']);
$user->hasAllRoles([...]);
$user->hasRealmRole('...');
$user->hasClientRole('viewer', 'billing');
$user->hasScope('orders:read');
$user->inGroup('engineering');
$user->keycloakRoles(); // ['admin', ...]
$user->keycloakGroups();
$user->keycloakToken(); // KeycloakToken, or null when the current token belongs to someone else
The helpers only answer true when the current token belongs to this user (matched by
keycloak_id), so checking roles of another user model returns false instead of leaking the caller's
roles.
Stateless API users (KeycloakUser) have the same methods.
UMA permissions (Authorization Services)¶
If you model resources, scopes and policies in Keycloak (Client → Authorization tab), ask Keycloak for a decision:
$oidc = Keycloak::oidc('api');
$oidc->checkPermission($token->jwt(), 'invoice#read'); // resource#scope
$oidc->checkPermission($token->jwt(), ['invoice#read', 'report']); // all of them
$oidc->permissions($token->jwt()); // [['rsname' => 'invoice', 'scopes' => ['read']], ...]
Decisions are cached for token.introspection_cache_ttl seconds (default 30s) per token and permission set.
The audience defaults to the guard's client_id (the resource server).
1.x KCAuth facade¶
The 1.x helpers still work and now read the current token: