Skip to content
P.M.C P.M.C P.M.C Documentation

User Impersonation

1. What does this feature do? (High-Level Overview)

Section titled “1. What does this feature do? (High-Level Overview)”

User Impersonation allows authorized administrators to temporarily access the application as another user within a specific location context. This enables admins to troubleshoot issues, provide support, and perform actions on behalf of users without needing their credentials.

2. Who is this for? (Roles & Permissions)

Section titled “2. Who is this for? (Roles & Permissions)”
  • Superadmin: Can start impersonation sessions for any active user, view all active sessions they created, and revoke any impersonation session.
  • Users with impersonate_users permission: Can start and view their own impersonation sessions (permission must be explicitly granted).

Required Permission: impersonate_users (global permission)

3. Business Rules & Enforcements

Section titled “3. Business Rules & Enforcements”
  • Rule 1: Users cannot impersonate themselves (self-impersonation is blocked).
  • Rule 2: Only ACTIVE users can be impersonated (inactive/disabled users are blocked).
  • Rule 3: Impersonation is location-scoped - the target user must have active access to the specified location.
  • Rule 4: Only ACTIVE locations can be used for impersonation.
  • Rule 5: Impersonation tokens have a configurable time-to-live (TTL) with minimum 1 minute and maximum 24 hours (1440 minutes).
  • Rule 6: All impersonation actions are fully audited and logged with actor (impersonator) and effective user (target) information.
  • Rule 7: Impersonation sessions automatically expire after the TTL period.
  • Rule 8: Superadmins can manually revoke any impersonation session at any time.

4. UI Placement

Section titled “4. UI Placement”

User Interface Components

Section titled “User Interface Components”

Impersonate Button:

  • Location: Employees (or Users in Admin View)> Admin Users List
  • Position: Actions column in the user table
  • Appearance: Person outline icon button
  • Visibility: Only visible to users with impersonate_users permission

Impersonation Banner:

  • Location: Top of application header (global)
  • Position: Sticky banner above main navigation
  • Visibility: Always visible during active impersonation session
  • Features: User name display, exit button

Confirmation Dialog:

  • Trigger: Clicking the impersonate button
  • Contents: User info, session duration selector, location selector, reason selector

For detailed UI usage instructions, see: Impersonation UI Guide For API usage details, see: Start Impersonation and Manage Sessions

5. How-To Guide (Step-by-Step)

Section titled “5. How-To Guide (Step-by-Step)”

Scenario A: Using the impersonation UI (recommended for most users)

See: Impersonation UI Guide - Complete walkthrough of the web interface

Scenario B: Stopping and managing sessions

See: Manage Impersonation Sessions - Session management operations

Scenario C: Understanding audit trails and security

See: Impersonation Audit Trail - Comprehensive audit logging details

6. What happens if…? (Edge Cases / FAQ)

Section titled “6. What happens if…? (Edge Cases / FAQ)”

  • Q: What happens if the target user is deleted while an impersonation session is active?

    • A: The impersonation token is automatically deleted from the database (cascading foreign key). The next request with that token will fail with an “invalid token” error.

  • Q: What happens if the target user is deactivated while being impersonated?

    • A: The active session continues until the token expires or is stopped/revoked. However, no new impersonation sessions can be created for inactive users.

  • Q: Can multiple admins impersonate the same user simultaneously?

    • A: Yes, multiple administrators can have active impersonation sessions for the same target user. Each session has a unique impersonation_id and is tracked independently.

  • Q: What happens to impersonation sessions if the location is deactivated?

    • A: Active sessions continue until expiration. New impersonation sessions cannot be created for inactive locations.

  • Q: Can the target user see that they are being impersonated?

    • A: Not directly through the UI. However, all actions are logged in the audit trail with both the actor (impersonator) and effective user (target) information.

  • Q: What happens to old impersonation tokens?

    • A: Expired tokens remain in the database for audit purposes. A cleanup command (php artisan impersonation:cleanup) can be run to delete tokens that have been expired for more than 7 days (configurable).

System Architecture

Section titled “System Architecture”

Token Management

Section titled “Token Management”
  • Impersonation uses JWT (JSON Web Token) with custom claims
  • Tokens are stored as SHA-256 hashes in the database
  • Each session has a unique impersonation_id (UUID)
  • Tokens include impersonator ID, target user ID, location context, and scopes

Security Features

Section titled “Security Features”
  • Permission-based access control
  • Token expiration (automatic)
  • Manual revocation capability
  • Comprehensive audit logging
  • Dual-user context (actor + effective user)
  • Response headers indicate active impersonation

Audit Trail

Section titled “Audit Trail”

All impersonation activities are logged at multiple levels:

  • Token creation, usage, and revocation in impersonation_tokens table
  • Activity log entries via Spatie Activity Log
  • Request-level audit logs in audit_logs table
  • Standard Laravel logs for administrative actions

See: Impersonation Audit Trail for details.