Nova Impersonate Laravel Package

Getting Started

Install the package into the Nova app and confirm Nova’s package discovery picks it up:

composer require kabbouchi/nova-impersonate

Add the field to the Nova resource that represents your authenticatable users, usually app/Nova/User.php:

use Kabbouchi\NovaImpersonate\Impersonate;

public function fields(NovaRequest $request)
{
    return [
        ID::make()->sortable(),
        // ...
        Impersonate::make()
            ->onlyOnDetail()
            ->canSee(fn (NovaRequest $request) => $request->user()->isAdmin()),
    ];
}

Look first at:

• The package README for the current install and route names.
• src/Impersonate.php for the field API and available meta/options.
• The package service provider, routes, and controller for the actual impersonation and “leave” endpoints.
• The Nova JS component if the button behavior or redirect is unclear.

The first practical use case is support/debugging: an admin opens a user’s Nova detail page, clicks Impersonate, reproduces the user’s issue in the application, then uses the package’s leave route to return to their admin account. Test this in staging with a non-admin user before enabling it in production.

Implementation Patterns

Use impersonation as a privileged support workflow, not as a general-purpose login shortcut.

• Put the field on detail pages only to reduce accidental clicks and index clutter.
• Authorize both field visibility and the impersonation endpoint. canSee only hides UI; the route still needs protection.
• Restrict who can be impersonated. For example, prevent admins from impersonating other admins or high-risk accounts.

// app/Nova/User.php
Impersonate::make('Login as user')
    ->onlyOnDetail()
    ->canSee(fn (NovaRequest $request) =>
        $request->user()->can('impersonate', $this->resource)
    ),

// app/Policies/UserPolicy.php
public function impersonate(User $user, User $target): bool
{
    return $user->isAdmin()
        && ! $target->isAdmin()
        && $user->isNot($target);
}

If your app uses a non-default auth guard, keep the Nova guard and impersonation guard aligned. The exact API depends on the installed version; check the field class/README, but it is commonly configured through field meta or package config:

Impersonate::make()
    ->withMeta(['guard' => 'web']);

Provide an obvious “stop impersonating” path outside Nova. If the package exposes a leave route, wire it into your app layout:

@impersonating
<form method="POST" action="{{ route('impersonate.leave') }}">
    @csrf
    <button type="submit">Return to admin</button>
</form>
@endimpersonating

Add an audit trail around the workflow: record the original admin ID, target user ID, timestamp, IP, and user agent. If the package does not emit events in your version, log inside middleware around the impersonation route or in your own thin controller wrapper.

For tests, exercise the route rather than only the field:

$this->actingAs($admin)
    ->post(route('nova-impersonate.start', $user))
    ->assertRedirect();

$this->assertAuthenticatedAs($user);

Use the package route name from the installed version; inspect php artisan route:list | grep -i impersonate.

Gotchas and Tips

• Guard mismatch is the most common failure. Nova may use web, while your app uses an admin guard or custom provider. Impersonating across guards can log the admin out, produce a 403, or authenticate against the wrong model.
• UI visibility is not security. Protect the route/controller with middleware, policies, or gates. Do not rely on canSee alone.
• Redirect loops are easy to create. If the impersonated user cannot access Nova or your post-impersonation redirect points back to Nova, the admin can get bounced or trapped. Send impersonated users to the application, and always test the leave flow.
• Always provide a visible exit. If the only leave link lives in Nova and the impersonated user cannot reach Nova, support staff can get stuck. Add a global “stop impersonating” banner/button.
• Impersonation is session-based. Queued jobs, scheduled commands, and separate API requests do not automatically inherit the impersonated identity. Pass the acting user explicitly when auditing or running privileged work.
• Audit and restrict it. Impersonation bypasses normal password/2FA checks. Treat it like production support access: limit roles, log usage, and consider disabling it outside staging or approved support accounts.
• Watch Nova major-version compatibility. This is a small field package; pin the version and verify the JS component still renders after Nova upgrades.
• Inspect the source when behavior is unclear. Route names, guard options, redirect behavior, and leave endpoints are small enough to verify quickly in src/, routes/, and the published JS/assets.
• Prefer detail-only usage. Index-page buttons are convenient but increase the chance of impersonating the wrong user. A detail page gives the admin more context before clicking.
• If the package does not fit your guard/redirect needs, wrap it. A small custom Nova action or controller around the same impersonation mechanism is often cleaner than fighting package defaults.