Step 05 · Assign access with Grants

Goal: the payoff. Assign access to Alice with the Grant model, then ask the PDP and see a real
ALLOW. Ask it about Bob — who has nothing — and see a fail-closed DENY. Then try a time-boxed grant,
an app-scoped grant, and deny-overrides.

The Grant model

Every assignment is a row in iam_grants, created through
Padosoft\Iam\Domain\Authorization\Models\Grant. The fields you’ll use:

1. Grant Alice a permission, directly

Open tinker and give Alice (user:1) the warehouse:stock.adjust permission:

php artisan tinker

>>> use Padosoft\Iam\Domain\Authorization\Models\Grant;

>>> Grant::query()->create([
...     'subject_type'   => 'user',
...     'subject_id'     => '1',                      // Alice
...     'privilege_type' => 'permission',
...     'privilege_key'  => 'warehouse:stock.adjust',
...     'effect'         => 'permit',
...     'valid_from'     => now(),
...     'source'         => 'tutorial',
... ]);

2. Ask the PDP — the real ALLOW / DENY

The Policy Decision Point is the only authority on allow/deny. Resolve it from the container and call
check() — this is the exact API the demo app and the server’s own test suite use:

>>> use Padosoft\Iam\Contracts\Authorization\AuthorizationEngine;
>>> $pdp = app(AuthorizationEngine::class);

// Alice has a permit grant → ALLOW
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '1'], 'permission' => 'warehouse:stock.adjust', 'explain' => true]);
=> [ "allowed" => true, "matched" => [[ "type" => "permission", "key" => "warehouse:stock.adjust" ]], "explanation" => [...] ]

// Bob has nothing → fail-closed DENY
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '2'], 'permission' => 'warehouse:stock.adjust']);
=> [ "allowed" => false, "matched" => [], ... ]

// Alice for a permission she wasn't granted → DENY
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '1'], 'permission' => 'warehouse:stock.read']);
=> [ "allowed" => false, ... ]

The check() input and array output:

3. The same access via a role grant

Instead of one permission, grant Alice the role — the PDP expands it to every permission the role holds:

// remove the direct grant first (optional), then grant the role
>>> Grant::query()->create([
...     'subject_type'   => 'user',
...     'subject_id'     => '1',
...     'privilege_type' => 'role',
...     'privilege_key'  => 'warehouse:stock_operator',
...     'effect'         => 'permit',
...     'valid_from'     => now(),
...     'source'         => 'tutorial',
... ]);

// now BOTH of the role's permissions resolve for Alice
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '1'], 'permission' => 'warehouse:stock.read'])['allowed'];
=> true
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '1'], 'permission' => 'warehouse:stock.adjust'])['allowed'];
=> true

One role grant, both permissions — that’s RBAC. Assign the job, not a checklist.

4. Time-boxed access

A grant only counts inside its [valid_from, valid_until] window — the check is fail-closed outside it:

// expired yesterday → DENY
>>> Grant::query()->create([
...     'subject_type' => 'user', 'subject_id' => '3',
...     'privilege_type' => 'permission', 'privilege_key' => 'warehouse:stock.read',
...     'effect' => 'permit',
...     'valid_from' => now()->subDays(2), 'valid_until' => now()->subDay(),
... ]);
>>> $pdp->check(['subject' => ['type' => 'user', 'id' => '3'], 'permission' => 'warehouse:stock.read'])['allowed'];
=> false     // the window has closed

Set valid_until to now()->addDay() instead and the same subject is allowed — until the window closes.
Grants can also be revoked ($grant->revoke('user:admin')) and support just-in-time PIM activation; see
Access requests.

5. Scope a grant to one application

A grant with an application_key only authorizes checks for that app — perfect isolation between apps:

>>> Grant::query()->create([
...     'subject_type' => 'user', 'subject_id' => '1',
...     'application_key' => 'warehouse',
...     'privilege_type' => 'permission', 'privilege_key' => 'warehouse:stock.read',
...     'effect' => 'permit', 'valid_from' => now(),
... ]);

>>> $pdp->check(['subject' => ['type'=>'user','id'=>'1'], 'permission' => 'warehouse:stock.read', 'application' => 'warehouse'])['allowed'];
=> true
>>> $pdp->check(['subject' => ['type'=>'user','id'=>'1'], 'permission' => 'warehouse:stock.read', 'application' => 'other-app'])['allowed'];
=> false     // out of scope

6. Deny-overrides — a deny always wins

If any applicable grant denies, the result is deny — even alongside a permit. This is the safety rule:

>>> Grant::query()->create([
...     'subject_type' => 'user', 'subject_id' => '1',
...     'privilege_type' => 'permission', 'privilege_key' => 'warehouse:stock.adjust',
...     'effect' => 'deny', 'valid_from' => now(),
... ]);
>>> $pdp->check(['subject' => ['type'=>'user','id'=>'1'], 'permission' => 'warehouse:stock.adjust', 'explain' => true])['allowed'];
=> false     // the deny beats the permit

>>> Grant::query()->where('subject_id','1')->where('effect','deny')->where('privilege_key','warehouse:stock.adjust')->delete();

What you just did

Next: stop using tinker — reach the very same decision from application code through
laravel-iam-client.

→ Step 06 · Connect a client

Deeper references: Ask the PDP ·
Deny-overrides & fail-closed · Access requests