Handle step-up assurance

Motivation

Some actions are permitted only at a higher assurance level (AAL) — for example, deleting an invoice
might require a freshly re-authenticated session. The PDP can answer “permitted, but step up first”. This
client makes that the safe default: such a permit does not pass a gate until the step-up is satisfied.

The two fields

An IamDecision carries:

• allowed — the raw PDP verdict (the policy would permit).
• requiresStepUp — true when that permit is conditional on a higher AAL.
• requiredAal — the level the subject must reach (e.g. aal2), when provided.

And the derived guard:

Iam::can(), the iam.can middleware, and the Gate adapter all gate on granted() — so a low-AAL session
is never let through on an allowed-but-step-up permit.

What you see by default

So out of the box, an action requiring step-up is simply blocked (403 via middleware, false via the
facade/Gate). That’s correct and safe — but if you want to offer the step-up, use check().

Driving a step-up flow

Use Iam::check() and branch on the decision instead of letting middleware hard-deny:

use Padosoft\Iam\Client\Facades\Iam;

public function destroy(Request $request, Invoice $invoice)
{
    $decision = Iam::check($request->user(), 'billing:invoices.delete', [
        'resource' => (string) $invoice->getKey(),
        'aal'      => session('current_aal', 'aal1'),  // tell the PDP the current level
    ]);

    if ($decision->requiresStepUp) {
        // Permitted in principle — send the user to re-authenticate at a higher AAL.
        return redirect()
            ->route('auth.step-up', ['required' => $decision->requiredAal, 'return' => url()->current()]);
    }

    abort_unless($decision->granted(), 403);

    $invoice->delete();

    return back();
}

Where step-up is enforced for you

So routes and Blade stay safe automatically; you only opt into a re-auth UX where you call check().

Gotchas

See also

• granted() vs allowed
• Ask IAM with the facade
• The decision contract