User Impersonation

Overview

User Impersonation allows administrators to temporarily log in as another user to troubleshoot issues, test permissions, or provide support without needing the user's password. This powerful feature lets you see exactly what a user sees and experience the system from their perspective, making it invaluable for debugging permission issues and providing user support.

Note: This feature is currently planned for future implementation. This documentation describes how it will work when available.

Accessing Impersonation

Navigation: Dashboard > Users > [Select User] > Impersonate

Required Permission: users.impersonate (planned)

Key Features

• Seamless Login: Log in as any user without their password
• Full User Experience: See exactly what the user sees
• Permission Testing: Test role and permission configurations
• Safe Exit: Easy return to your own account
• Audit Trail: All impersonation sessions are logged
• Security Restrictions: Cannot impersonate super admins

When to Use Impersonation

Troubleshooting Permission Issues

When a user reports they cannot access a feature:

1. Impersonate the user
2. Try to access the feature yourself
3. See the exact error or restriction they're experiencing
4. Identify which permission is missing
5. Exit impersonation and fix the permission issue

Testing New Roles

Before assigning a new role to real users:

1. Create a test user with the new role
2. Impersonate the test user
3. Navigate through the system to verify access
4. Ensure they can access what they should and cannot access what they shouldn't
5. Adjust the role's permissions as needed

User Support

When helping a user with a specific issue:

1. Impersonate the user to see their exact view
2. Reproduce the issue they're experiencing
3. Identify the cause
4. Exit impersonation and provide guidance or fix the issue

Quality Assurance

When testing new features:

1. Impersonate users with different roles
2. Verify the feature works correctly for each role
3. Ensure proper permission checks are in place
4. Test edge cases and error handling

How to Impersonate a User

Starting Impersonation

Method 1: From User List

1. Navigate to Dashboard > Users
2. Find the user you want to impersonate
3. Click the "Impersonate" button (mask icon) next to their name
4. Confirm the impersonation
5. You'll be logged in as that user

Method 2: From User Details

1. Navigate to Dashboard > Users
2. Click on a user to view their details
3. Click the "Impersonate User" button at the top
4. Confirm the impersonation
5. You'll be logged in as that user

What Happens:

• Your current session is preserved
• You're logged in as the selected user
• A banner appears at the top indicating you're impersonating
• The banner shows who you're impersonating and provides an exit button
• All actions are performed as the impersonated user
• Your impersonation session is logged in the audit system

During Impersonation

Visual Indicators:

• A prominent banner at the top of every page shows:
  • "You are impersonating [User Name]"
  • The user's email address
  • A "Stop Impersonation" button
• The banner is color-coded (e.g., orange/yellow) to make it obvious
• The banner is always visible and cannot be dismissed

What You Can Do:

• Navigate through the entire system as the user
• See exactly what they see (same permissions, same data)
• Perform actions on their behalf (with caution)
• Test features and functionality
• Identify permission issues

What You Cannot Do:

• Change the user's password (security protection)
• Delete the user's account
• Impersonate another user while already impersonating
• Access features that require your original admin permissions

Stopping Impersonation

Method 1: Using the Banner

1. Click the "Stop Impersonation" button in the banner
2. You'll be immediately returned to your own account
3. You'll be redirected to the users list or dashboard

Method 2: Using the Menu

1. Click on your profile menu
2. Select "Stop Impersonation"
3. You'll be returned to your own account

What Happens:

• Your impersonation session ends
• You're logged back in as yourself
• Your original session is restored
• The impersonation end is logged in the audit system
• You're redirected to a safe page (usually the users list)

Security Considerations

Who Can Impersonate

Required Permission:

• users.impersonate permission is required
• Typically only granted to super admins and senior administrators
• Should be carefully controlled due to its power

Restrictions:

• Cannot impersonate super admin users (security protection)
• Cannot impersonate yourself (no point)
• May have IP restrictions or 2FA requirements
• May require additional authentication for sensitive accounts

What's Logged

Every impersonation session is logged in the audit system:

• Start of Impersonation: Who impersonated whom, when, and from which IP
• Actions During Impersonation: All actions performed while impersonating
• End of Impersonation: When the session ended and how (manual exit, timeout, etc.)
• Failed Attempts: Any failed impersonation attempts

Best Practices

Do:

• Use impersonation for legitimate troubleshooting and testing
• Always exit impersonation when done
• Be aware that your actions are performed as the user
• Document why you impersonated a user (in tickets, notes, etc.)
• Inform users if you need to impersonate them for support

Don't:

• Use impersonation to access data you shouldn't see
• Perform sensitive actions while impersonating without user consent
• Leave impersonation sessions running unattended
• Impersonate users for curiosity or unauthorized purposes
• Share impersonation access with unauthorized personnel

Privacy and Compliance

• Impersonation should comply with your organization's privacy policies
• Users may need to be informed about impersonation capabilities
• Some regulations may require user consent for impersonation
• All impersonation is logged for compliance and auditing
• Consider implementing additional safeguards for sensitive accounts

Common Tasks

Testing a New Role Configuration

1. Create a test user account
2. Assign the new role to the test user
3. Impersonate the test user
4. Navigate through the system testing each feature
5. Document what works and what doesn't
6. Exit impersonation
7. Adjust the role's permissions as needed
8. Repeat until the role is configured correctly

Debugging a Permission Issue

1. User reports they cannot access a feature
2. Find the user in the users list
3. Impersonate the user
4. Try to access the feature they reported
5. Note the exact error or behavior
6. Check the user's roles and permissions
7. Exit impersonation
8. Fix the permission issue
9. Optionally impersonate again to verify the fix

Providing User Support

1. User needs help with a specific task
2. Impersonate the user to see their exact view
3. Identify the issue or confusion
4. Exit impersonation
5. Provide clear instructions or make necessary changes
6. Follow up with the user

Permissions

The following permissions control access to impersonation:

• users.impersonate: Can impersonate other users (planned)
• users.view_impersonation_logs: Can view impersonation audit logs (planned)

Permission Hierarchy:

• Impersonation is a high-privilege permission
• Should only be granted to trusted administrators
• Super admins have this permission by default
• Regular admins may or may not have it depending on policy

Tips and Best Practices

• Always Exit: Make it a habit to exit impersonation immediately when done
• Use for Testing: Impersonation is perfect for testing new roles and permissions
• Document Usage: Keep notes on why you impersonated users for audit purposes
• Be Careful: Remember that actions performed while impersonating are done as that user
• Check the Banner: Always verify you're impersonating the correct user
• Time Limits: Don't leave impersonation sessions running for extended periods
• Inform Users: Consider informing users when you need to impersonate them for support
• Test Regularly: Use impersonation to regularly test different user experiences

Troubleshooting

Problem: Cannot Impersonate a User

Solution:

• Verify you have the users.impersonate permission
• Check if the user is a super admin (cannot be impersonated)
• Ensure you're not already impersonating someone
• Check if there are IP restrictions or 2FA requirements
• Contact a super admin if you need impersonation access

Problem: Cannot Exit Impersonation

Solution:

• Look for the banner at the top of the page
• Click the "Stop Impersonation" button
• If the banner is missing, try logging out completely
• Clear your browser cache and cookies
• Contact support if the issue persists

Problem: Actions Not Working While Impersonating

Solution:

• Remember you have the impersonated user's permissions, not your own
• The user may not have permission to perform that action
• This is actually helpful for testing permission configurations
• Exit impersonation to perform admin actions

Problem: Impersonation Banner Not Visible

Solution:

• The banner should always be visible at the top
• Try refreshing the page
• Check if you're actually impersonating (check the audit logs)
• If the banner is missing, log out and log back in
• Report this as a bug if it persists

Problem: Accidentally Performed Action While Impersonating

Solution:

• Actions performed while impersonating are done as that user
• Check the audit logs to see what was done
• Undo the action if possible
• Inform the user if necessary
• Be more careful in the future

Related Modules

• Users: Manage user accounts and access impersonation from user details
• Roles: Test role configurations using impersonation
• Permissions: Verify permission assignments by impersonating users
• Audit Logs: Review all impersonation sessions and activities
• Security Settings: Configure impersonation security requirements