Impersonation UI Guide

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

The Impersonation UI provides administrators with an intuitive interface to start, monitor, and stop user impersonation sessions. The UI includes visual indicators, confirmation dialogs, session timers, and safety warnings to ensure secure and transparent impersonation operations.

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

Superadmin: Full access to all impersonation UI components.
Users with impersonate_users permission: Can access the impersonation button and related UI components.

UI Availability:

The impersonation button only appears for users with the required permissions
All UI components automatically hide/disable when permissions are insufficient

3. Business Rules & Enforcements

Rule 1: The impersonation button is disabled when an impersonation session is already active.
Rule 2: Users must select a location before confirming impersonation (location is required).
Rule 3: Session duration must be selected from predefined options (15 min to 8 hours).
Rule 4: The impersonation banner is always visible during an active session and cannot be dismissed (only closed by stopping impersonation).
Rule 5: A warning indicator appears on the banner when less than 10 minutes remain.
Rule 6: The page automatically reloads after starting impersonation to refresh the user context.
Rule 7: All impersonation actions require explicit confirmation from the administrator.

4. UI Placement

Impersonate Button

Location: Admin Users List page (/admin/users-list) Component: <app-impersonate-button> Position: Action column in user table, alongside other user management buttons

Location: Top of the application header (global)
Component: <app-impersonation-banner>
Position: Sticky header element, always visible above main navigation

Confirmation Dialog

Location: Modal overlay (appears on button click)
Component: <app-impersonation-confirm-dialog>

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

Scenario A: Starting an Impersonation Session (Admin Workflow)

Navigate to Users List
- Go to the main menu
- Click on Employees
- The Admin Users List displays with all system users
Locate the Target User
- Scroll or search for the user you want to impersonate
- In the Actions column, find the impersonation button (person outline icon)
Click the Impersonate Button
- Hover over the button to see the tooltip: “Impersonate user: [User Name]”
- If the button is disabled, check the tooltip for the reason (e.g., “Impersonation already active”)
- Click the button to open the confirmation dialog
Configure Impersonation Settings

The confirmation dialog displays:

User Information Card:
- User name
- Email address
- Role (if available)
Configuration Options:

a. Session Duration (Required)
- Choose from dropdown:
  - 15 minutes
  - 30 minutes
  - 1 hour (default)
  - 2 hours
  - 4 hours
  - 8 hours
b. Location (Required - marked with red asterisk)
- Select the location context for impersonation
- Only active locations are selectable
- Inactive locations appear grayed out
c. Reason (Optional but recommended)
- Choose from predefined reasons:
  - Technical Support
  - Incident Resolution
  - User Assistance
  - System Testing
  - Data Verification
  - Training/Demo
  - System Configuration
  - Other
Warning Messages:
- ⚠️ “You are about to impersonate another user. All actions performed will be logged and associated with your administrator account.”
- 🔒 “This action will be recorded in the system audit logs.”
Confirm Impersonation
- Ensure location is selected (Confirm button is disabled without location)
- Click Confirm Impersonation button
- Loading spinner appears while processing
Session Starts
- Success notification appears: “Impersonation started: [User Name]”
- Page automatically reloads to refresh user context
- Impersonation banner appears at top of screen

Scenario B: Monitoring an Active Session

Visual Indicators:

Impersonation Banner (Top of Screen)

The banner displays:
- 👤 Person icon
- “Acting as: [User Name]”
- ⏱️ Timer badge (appears when < 10 minutes remaining)
- ❌ Close button to exit impersonation
Banner States:
- Normal: Blue/neutral color with user name
- Warning: Orange/yellow color when time is running out
- Tooltip: Hover over banner for detailed information:
```
Impersonating User
━━━━━━━━━━━━━━
Name: John Doe
Email: john.doe@example.com
Role: RBT, Analyst
Time remaining: 45m 23s

Click × to exit impersonation
```
Time Display
- Format: “Xh Ym remaining” (for > 1 hour)
- Format: “Ym Zs remaining” (for < 1 hour)
- Format: “Expires in Xm Ys” (when < 10 minutes)
- Shows “Expired” if session has expired
Real-Time Updates
- Timer updates every second
- Warning indicator appears automatically at 10-minute threshold
- Session ends automatically at expiration

Scenario C: Stopping an Impersonation Session

Click the Close Button (×) on Banner
- Located on the right side of the impersonation banner
- Click the × icon
Confirmation Dialog Appears

Dialog content:
- Title: “Exit Impersonation?”
- Message: “You are about to stop impersonating: [User Name]”
- Info: “You will be returned to your administrator account.”
Options:
- “Cancel” button (gray) - Continues impersonation
- “Yes, Exit” button (red) - Confirms exit
Session Termination Process

If confirmed:
- Loading dialog appears: “Exiting Impersonation…”
- API call made to stop the session
- Success notification: “Session Ended - Impersonation session has been successfully terminated.”
- Message: “Returning to your administrator account…”
- Automatic redirect to dashboard
- Admin user context restored
Session Restored
- You’re back in your administrator account
- Impersonation banner disappears
- Original location context restored
- All admin permissions restored

Scenario D: Automatic Session Expiration

What Happens:

10-Minute Warning
- Banner turns orange/yellow
- Timer badge becomes prominent
- Updates every second
Session Expires
- Automatic detection via client-side timer
- SweetAlert2 notification appears:
  - Icon: ⚠️ Warning
  - Title: “Session Expired”
  - Message: “Your impersonation session has expired. The session time limit has been reached. You will be automatically returned to your administrator account.”
  - Auto-closes after 3 seconds with progress bar
Return Transition
- Loading notification: “Returning to Admin - Restoring your administrator session…”
- Automatic API call to clean up session
- Redirect to dashboard
- Admin context fully restored

User Cannot:

Continue working with an expired session
Dismiss the expiration notification
Extend the expired session (must create new session)

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

Q: What happens if I try to start impersonation while already impersonating someone?
- A: The impersonate button is automatically disabled. The tooltip shows: “Impersonation already active ([Current User Name]). End current impersonation to start another.” You must stop the current session before starting a new one.
Q: What happens if I refresh the page during an impersonation session?
- A: The session persists across page refreshes. The impersonation state is stored in sessionStorage, and the banner reappears automatically. The timer continues counting down from where it left off.
Q: What happens if I close the browser tab during impersonation?
- A: The session token remains valid on the server until expiration. If you reopen the application in the same browser session, the impersonation state is restored. If you close the browser entirely, the session is lost locally (but still valid server-side until expiration).
Q: Can I open multiple tabs while impersonating?
- A: Yes, all tabs in the same browser session share the impersonation state via sessionStorage. All tabs will show the banner and use the impersonation token. Stopping the session in one tab will affect all tabs after their next API call.
Q: What happens if the session expires while I’m in the middle of filling out a form?
- A: The expiration dialog appears, and after 3 seconds you’re redirected to the dashboard. Unsaved form data may be lost. Consider setting a longer session duration for complex tasks, or save your work frequently.
Q: Can I see all active impersonation sessions I’ve created?
- A: This functionality exists in the API (GET /api/impersonate/active) but may not have a dedicated UI page yet. Contact your system administrator to view active sessions.
Q: What if I forget to stop the impersonation session?
- A: The session automatically expires after the configured TTL (Time To Live). The system will automatically terminate it and return you to your admin account. However, it’s best practice to manually stop sessions when done.
Q: Can I switch locations during an impersonation session?
- A: No, the location is fixed when the session starts. If you need to impersonate the same user in a different location, you must stop the current session and start a new one with the desired location.

UI Components Technical Details

ImpersonateButtonComponent

Selector: <app-impersonate-button>

Inputs:

userId (number, required) - ID of user to impersonate
userName (string, required) - Display name of user
userEmail (string, required) - User’s email address
userRole (string, optional) - User’s role for display
disabled (boolean, default: false) - Manually disable button
iconOnly (boolean, default: false) - Show icon without text

Outputs:

impersonationStarted - Emits when impersonation successfully starts

States:

Enabled: Button is clickable (admin has permission, no active session)
Disabled: Button is grayed out (active session, loading, or no permission)
Loading: Shows spinner icon during API call

Appearance:

Icon: person_outline (Material Icon)
Text: “Impersonate” (if not iconOnly)
Style: Icon button (Material)

Usage Example:

<app-impersonate-button
  [userId]="user.id"
  [userName]="user.name"
  [userEmail]="user.email"
  [userRole]="user.role"
  [iconOnly]="true"
  (impersonationStarted)="onImpersonationStarted()">
</app-impersonate-button>

ImpersonationBannerComponent

Selector: <app-impersonation-banner>

Features:

Automatic Visibility: Shows/hides based on impersonation state
Live Timer: Updates every second
Warning State: Changes appearance when < 10 minutes remaining
Tooltip: Detailed session information on hover
Stop Button: Integrated × button to end session

Visual States:

Normal:    [👤 Acting as: John Doe             ×]
Warning:   [👤 Acting as: John Doe ⏱️ 8m 42s   ×]
Stopping:  [👤 Acting as: John Doe    (spinner)]

Styling:

Normal: Neutral/info color scheme
Warning: Orange/yellow highlight
Close Button: Material icon button with hover effect

Usage Example:

<!-- Place in app header/layout -->
<app-impersonation-banner></app-impersonation-banner>

ImpersonationConfirmDialogComponent

Selector: <app-impersonation-confirm-dialog>

Form Fields:

Session Duration (Dropdown)
- Required: Yes
- Default: 60 minutes
- Options: 15, 30, 60, 120, 240, 480 minutes
Location (Dropdown)
- Required: Yes
- Shows all user locations
- Disabled locations are grayed out
- Must be selected to enable Confirm button
Reason (Dropdown)
- Required: No (optional but recommended)
- Predefined options for audit compliance
- Default: “Impersonate [User Name]”

Dialog Actions:

Cancel: Closes dialog without action
Confirm Impersonation:
- Disabled if location not selected
- Shows checkmark icon
- Primary color (blue)

User Experience Flows

Flow 1: Successful Impersonation

User Action                  → UI Feedback
─────────────────────────────────────────────────────────
Click "Impersonate" button   → Dialog opens
Select location + duration   → Form validates
Click "Confirm"              → Loading dialog
Session created              → Success notification
Page reloads                 → Banner appears
User acts as target          → All actions logged
Click "×" on banner          → Confirmation dialog
Confirm exit                 → Loading dialog
Session ended                → Success notification
Redirected to dashboard      → Admin context restored

Flow 2: Session Expiration

Event                        → UI Feedback
─────────────────────────────────────────────────────────
10 min remaining             → Banner turns orange
Timer shows warning          → "⏱️ 9m 45s"
Session expires              → Warning dialog (auto)
3-second countdown           → Progress bar
Dialog closes                → Loading transition
Cleanup API called           → "Returning to Admin"
Redirect to dashboard        → Admin context restored

Flow 3: Error Handling

Error                        → UI Feedback
─────────────────────────────────────────────────────────
API failure on start         → Error snackbar (7 sec)
Token expired mid-session    → Expiration dialog
Token revoked externally     → Revocation dialog
Network error                → Error notification
Invalid location selected    → Form validation error
Missing required field       → Button disabled

Accessibility Features

Keyboard Navigation:

Dialog can be closed with ESC key
Tab navigation through form fields
Enter key confirms dialog (when valid)

ARIA Labels:

Impersonate button: aria-label="Impersonate user"
Close button: aria-label="Exit impersonation"
Dialog: Proper ARIA roles and labels

Visual Indicators:

Clear color coding (blue=normal, orange=warning, red=error)
Icon + text combinations (not relying on color alone)
Loading spinners for async operations
Disabled state clearly visible

Screen Reader Support:

All buttons have descriptive labels
Form fields properly associated with labels
Status changes announced
Error messages linked to form fields

Best Practices for Administrators

Always Provide a Reason
- Helps with audit compliance
- Makes logs more meaningful
- Shows accountability
Choose Appropriate Session Duration
- Short tasks: 15-30 minutes
- Troubleshooting: 1-2 hours
- Complex work: 4+ hours
- Never leave sessions running indefinitely
Monitor the Timer
- Watch for warning indicator
- Save work before expiration
- Stop session manually when done
Verify Location Context
- Ensure correct location is selected
- Remember: location cannot be changed mid-session
- Create new session if wrong location
End Sessions Promptly
- Don’t leave sessions active unnecessarily
- Click the × button when finished
- Reduces security risk and audit clutter
Communicate with Users
- Inform users if you need to impersonate them
- Explain what you’re doing and why
- Builds trust and transparency
Review Audit Logs
- Periodically check your impersonation history
- Verify all actions were intentional
- Report any suspicious activity

Troubleshooting

Issue: Impersonate button doesn’t appear

Possible Causes:

User doesn’t have impersonate_users permission
User is not SUPERADMIN
Frontend permission check failing

Solution:

Verify user role: Must be SUPERADMIN
Check user permissions in database
Clear cache and reload page

Issue: Button is disabled

Possible Causes:

Impersonation session already active
Component is loading
Manually disabled via input

Solution:

Check banner at top - if visible, stop current session first
Wait for loading to complete
Check component inputs in console

Issue: Dialog won’t confirm

Possible Causes:

Location not selected (required field)
Form validation error

Solution:

Ensure location dropdown has a value selected
Check for red error messages
Verify location is active (not disabled)

Issue: Session doesn’t persist after page refresh

Possible Causes:

sessionStorage cleared
Browser privacy mode
Admin logged out

Solution:

Check if admin token still exists
Disable browser privacy mode
Verify sessionStorage is enabled

Issue: Timer showing incorrect time

Possible Causes:

System clock mismatch
Timezone issues

Solution:

Verify server and client clocks are synchronized
Check browser timezone settings
Token expiration is based on server time

Issue: Session won’t stop

Possible Causes:

Network error
API endpoint unavailable
Token already revoked

Solution:

Check network connection
Try again in a few seconds
Verify API is accessible
If persists, contact system administrator

Security Considerations

Client-Side Security:

Impersonation token stored only in sessionStorage (not localStorage)
Token cleared on logout
State validation on every page load
Automatic cleanup on expiration

UI Security Features:

Clear visual indicators of impersonation
Warning messages before starting session
Audit log reminders
Cannot dismiss banner during session
Confirmation required to exit

Best Practices:

Never share impersonation tokens
Don’t screenshot the token
Always stop sessions when done
Report suspicious impersonation activity
Review audit logs regularly

Impersonation UI Guide

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

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

3. Business Rules & Enforcements

4. UI Placement

Impersonate Button

Impersonation Banner

Confirmation Dialog

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

Scenario A: Starting an Impersonation Session (Admin Workflow)

Scenario B: Monitoring an Active Session

Scenario C: Stopping an Impersonation Session

Scenario D: Automatic Session Expiration

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

UI Components Technical Details

ImpersonateButtonComponent

ImpersonationBannerComponent

ImpersonationConfirmDialogComponent

User Experience Flows

Flow 1: Successful Impersonation

Flow 2: Session Expiration

Flow 3: Error Handling

Accessibility Features

Best Practices for Administrators

Troubleshooting

Issue: Impersonate button doesn’t appear

Issue: Button is disabled

Issue: Dialog won’t confirm

Issue: Session doesn’t persist after page refresh

Issue: Timer showing incorrect time

Issue: Session won’t stop

Security Considerations