Impersonation

An administrator can sign in as one of your users to see what they see. The feature exists because the alternative is worse: without it, "I cannot find the button you mean" gets answered by asking a customer for their password, or by an engineer running queries against production. Both of those are impersonation too, with no banner and no audit trail.

It is also the feature most likely to be built badly, so the rules below are enforced by the package rather than left to the screen that calls it. Read them before you leave it on.

The rules

1. An administrator may never be impersonated. Otherwise the panel is a privilege escalation ladder: an administrator who may not suspend a colleague becomes them, and does. The target is measured against the same ability that opens the panel, so redefining that ability redefines this too.

2. Nobody impersonates themselves, and a suspended account cannot be impersonated at all. There is nothing to see from inside a suspended account, because laraspring/auth closes that session on its next request; lift the suspension first, or read the account from the panel.

3. The real administrator stays in the session. Their identifier is written to laraspring_admin.impersonator before the login, so there is never an instant in which the session is the target's without being marked as borrowed. The session identifier is then regenerated, which migrates the data and stops a fixated session id from following the switch. It is deliberately not a second guard: an impersonated session is the target's session, and two authenticated users in one request is two chances for the wrong one to be charged, emailed or logged.

4. The banner is on every page. It is a shared Inertia prop rendered in the application shell rather than something the admin screens pass down, so it follows the impersonator into every corner of the product, including pages laraspring/admin has never heard of. An impersonation you can forget you are in is the one that ends with a support agent writing a note as somebody else.

5. Both ends are on the record. Starting and stopping each write a line to admin_actions naming the administrator and the target. The audit line is written before the session is touched, so a support session that fails halfway is still on the record.

6. Nothing destructive is possible while it lasts. See below.

7. The panel closes behind you. While impersonating, the administrator is somebody who is not an administrator, and the panel's own guard says so. The way back is the banner, not the panel.

What is blocked, and how to add your own

Impersonation is for looking. The three actions that turn looking into a takeover, changing the password, changing the email address and deleting the account, are exactly the three the real owner cannot undo and will not be told about, so they are refused for the duration.

The list is configuration, because your application's destructive routes are routes the package has never heard of:

// config/laraspring-admin.php
'impersonation' => [
    'enabled' => env('LARASPRING_ADMIN_IMPERSONATION', true),

    'blocked_routes' => [
        'profile.update',
        'profile.destroy',
        'password.update',
        'password.confirm',
        'two-factor.*',
        'organizations.destroy',
        'organizations.ownership.transfer',
        'billing.*',
        'invoices.destroy', // yours
    ],
],

Patterns, not exact names, because a feature's destructive routes usually share a prefix and listing them one by one is how the next one gets forgotten. The rule is applied by a middleware on the whole web group, so a route added next month is covered the moment its name matches.

Anything your users cannot undo belongs on that list. A good test: if the account's owner would need to contact support to reverse it, an impersonator should not be able to do it.

Turning it off

LARASPRING_ADMIN_IMPERSONATION=false

The start endpoint becomes a 404 and the button is never drawn. Suspensions, the users screens and the audit trail are unaffected.

What impersonation still cannot protect you from

It is a real session as a real user. Anything that is not on the blocked list happens as them, and the audit trail records that the session started, not every click inside it. If your product has actions where "who did this" is legally load-bearing, record the impersonator alongside the actor in your own tables: Laraspring\Admin\Support\Impersonation::impersonator() answers that in one call, and returns null when nobody is impersonating.