Masquerade
Allows privileged users to temporarily switch to another user account while maintaining a record of the original account for easy switching back.
masquerade
Install
composer require 'drupal/masquerade:8.x-2.0'
Overview
The Masquerade module provides a secure and intuitive way for administrators and privileged users to temporarily assume the identity of another user account. This is particularly useful for debugging, testing user-specific functionality, or providing support to users by experiencing the site from their perspective.
The module tracks the original user account in the session, allowing users to easily switch back to their own account at any time. Masquerade integrates seamlessly with Drupal's built-in user interface, including the Toolbar module and contextual links, providing a frictionless user experience.
Security is a core design principle of Masquerade. The built-in access control mechanism prevents privilege escalation by default - users can only masquerade as users with equal or fewer permissions than themselves. UID 1 (super admin) can masquerade as anyone, but no one can masquerade as UID 1 without explicit permission.
Features
- Temporarily switch to another user account while preserving the original session for easy return
- Autocomplete-enabled block form for quick user switching by username
- Toolbar integration showing 'Unmasquerade' link when masquerading
- Entity operation 'Masquerade as' on the administrative user listing page
- Role-based permissions allowing granular control over who can masquerade as which roles
- Built-in security preventing privilege escalation by default
- Custom access control via hook_masquerade_access for fine-grained control
- Session-based masquerade tracking with dedicated cache context
- Optional configuration to control whether masquerading updates the target user's last access time
- Extra field on user display to show masquerade link
- Migration support mapping D7 permissions to D8/D9 equivalents
Use Cases
Customer Support and Debugging
Support staff can masquerade as a customer to see exactly what they see, diagnose permission issues, or reproduce reported bugs without needing the customer's password. After resolving the issue, they can immediately switch back to their own account.
Content Review by Editors
Editors can masquerade as content authors to verify that submitted content appears correctly from the author's perspective, checking for proper field visibility, access restrictions, and workflow states.
Training and Documentation
Administrators creating training materials can masquerade as users with different roles to capture accurate screenshots showing exactly what each role sees, ensuring documentation reflects the actual user experience.
Role-Based Access Testing
During development or site configuration, developers can masquerade as users with specific roles to test that permissions and access restrictions are working correctly without creating multiple test accounts.
User Onboarding Assistance
Administrators can masquerade as newly created users to complete initial profile setup, configure preferences, or perform other onboarding tasks on behalf of users who may need assistance.
Tips
- UID 1 (super admin) can always masquerade as any user without additional permissions, but explicitly granting 'Masquerade as super user' permission is required for others to masquerade as UID 1
- The module uses session-based tracking, so masquerading survives page navigation but ends when the session expires or the browser is closed
- Use the Masquerade block for quick access to the masquerade form, or use the user listing's 'Masquerade as' operation for direct masquerading
- Masquerading triggers both hook_user_logout (for original user) and hook_user_login (for target user), allowing other modules to respond to the switch
- Custom access control can be implemented via hook_masquerade_access for scenarios like allowing masquerading as a 'demo' user without requiring broad permissions
Technical Details
Admin Pages 3
/masquerade
A page containing the masquerade form that allows users to switch to another user account by entering a username. This page is accessible to any user who has at least one masquerade permission.
/user/{user}/masquerade
Direct action URL to masquerade as a specific user. This route is typically accessed via the 'Masquerade as' operation on the user listing or from the masquerade link on user profiles.
/unmasquerade
Switches the user back to their original account. Only accessible when the user is currently masquerading.
Permissions 3
Hooks 1
hook_masquerade_access
Control access to masquerade as a specific target user. This hook allows modules to implement custom access logic beyond the default permission-based checks.
Troubleshooting 5
Check that you have the appropriate permissions. You need either 'Masquerade as any user' permission, or 'Masquerade as [role]' permissions for ALL roles the target user has. UID 1 requires the special 'Masquerade as super user' permission.
The operation only appears for users you have permission to masquerade as. If the target user has permissions you don't have, the link won't appear due to the built-in privilege escalation protection.
You must switch back to your original account before masquerading as a different user. Use the 'Unmasquerade' link in the toolbar or user menu.
This behavior can be controlled via the 'update_user_last_access' setting in masquerade.settings.yml. Set it to FALSE to prevent updates while masquerading.
Ensure the block is placed in a visible region, and that you have at least one masquerade permission. The block is hidden for anonymous users and for users currently masquerading (unless 'Show unmasquerade link' is enabled).
Security Notes 7
- Masquerade's default access control prevents privilege escalation - users cannot masquerade as someone with more permissions than themselves
- UID 1 receives special protection: only users with the explicit 'Masquerade as super user' permission can masquerade as the super admin
- The 'Masquerade as any user' and 'Masquerade as super user' permissions should only be granted to highly trusted administrative roles
- All masquerade events are logged including who masqueraded as whom and when they switched back
- CSRF token protection is enforced on masquerade and unmasquerade routes
- Session regeneration occurs during switching to prevent session fixation attacks
- Anonymous user masquerading is intentionally not supported - use private browsing instead