Documentation

Usage

After installation the plugin adds an impersonate icon to every row of Settings → Team → Administrators. Click it, confirm, and the backend reloads as that user. A banner on every page shows who you are viewing as, who you really are, the time left when a session lifetime is set, and a Leave impersonation button.

Impersonating needs the User impersonation permission, granted by default to super users and the Developer role.

Who cannot be impersonated

An attempt is refused with a flash message when the target is a super user, is your own account, is not activated or lacks backend access, or holds a permission you do not have while the privilege escalation guard is on. Nested impersonation is refused as well; leave the current one first.

Settings

Settings → Team → Impersonate needs the Manage impersonation settings permission, granted by default to super users and the Developer role. Impersonators without it cannot switch the safeguards off.

• Audit log — record every impersonation attempt in the system event log. Default: on.
• Block privilege escalation — refuse impersonating users who hold permissions the impersonator does not have. Super users are never blocked. Default: on.
• Session lifetime (minutes) — end the impersonation automatically after this many minutes. 0 disables the limit. Default: 0.

Audit log

Every attempt is written to Settings → Logs → Event Log as Impersonation started, stopped (info) or denied (warning) with these details:

An impersonation that ends because its lifetime expired is logged as stopped, like a manual exit.

Leaving impersonation

Use the banner button or the link on the access denied page. Should neither be reachable, open this address (with your backend URI) and confirm:

/backend/renatio/impersonate/leave

An impersonation that outlives the session lifetime ends on the next request with a notice.

Events

The plugin fires its own events, so another plugin or the project can send a mail, write an audit entry or react to a refusal. The names are available as constants on Renatio\Impersonate\Classes\Events.

Both users are Backend\Models\User instances; $impersonator and, for stopped, $target can be null when the account was deleted mid-session. Events fire after the audit log entry is written. Keep listeners cheap and non-throwing: an exception aborts the request, though the session and the log are already consistent by then. Listen in your plugin's boot():

use Illuminate\Support\Facades\Event;
use Renatio\Impersonate\Classes\Events;

Event::listen(Events::STARTED, function ($impersonator, $target) {
    traceLog($impersonator?->full_name . ' is now impersonating ' . $target->full_name);
});

Event::listen(Events::DENIED, function ($impersonator, $target, string $reason) {
    traceLog($impersonator?->full_name . ' was refused: ' . $reason);
});

The core model.auth.beforeImpersonate and model.auth.afterImpersonate events on Backend\Models\User keep firing as well, but they know nothing about refusals or expiry.

Upgrade guide

Versions not listed here need no action. Back up the database before upgrading.

Upgrading To 2.0.0

Plugin requires October CMS 3.0 or higher, Laravel 9.0 or higher and PHP >=8.0.

Upgrading To 3.0.1

Plugin requires October CMS 4.0 or higher.

Upgrading To 3.1.0

Security release. Upgrade every installation running 3.0.x. Plugin requires PHP 8.2 or higher. Run php artisan october:migrate.

The User impersonation permission is now granted by default only to super users and the Developer role; the Publisher role loses it. The new settings page at Settings → Team → Impersonate needs the separate Manage impersonation settings permission. Grant either to a custom role where needed.

The privilege escalation guard is on by default, so a non-super user can no longer impersonate anyone holding permissions they lack. Switch it off in the settings if you rely on that.

Leaving impersonation goes through /backend/renatio/impersonate/leave; the onStopImpersonateUser AJAX handler was removed. The plugin now fires renatio.impersonate.* events (see the README).