Using the User Impersonation Feature in DHIS2¶
Overview¶
User impersonation, also known as user switching, is a powerful feature provided in DHIS2 for administrative users to log in as another user. This feature is especially useful for troubleshooting or resolving user-related issues, as it allows an administrator to experience DHIS2 exactly as the user does.
This feature is built upon the SwitchUserFilter from Spring Security, but with additional configuration options.
Note
The feature is disabled by default. To enable it, you must set the
switch_user_feature.enabledproperty totruein yourdhis.conffile.This feature is considered experimental and is only meant to be called from configured IP address(s). Hence, to use it you must know the IP address from which you will be calling it and configure the
switch_user_allow_listed_ipsproperty in thedhis.conffile. This restriction might be removed in the future.
How it works¶
Impersonation is done through two API endpoints. Both use POST; opening them in the browser address bar (a GET request) will not work.
| Action | Request |
|---|---|
| Start impersonating | POST /api/auth/impersonate?username=<USERNAME> |
| Stop impersonating | POST /api/auth/impersonateExit |
While impersonating, every request in the same session runs as the impersonated user, with that user's authorities, sharing and organisation units.
A successful request returns:
{ "status": "IMPERSONATION_SUCCESS", "username": "<USERNAME>" }
and exiting returns "status": "IMPERSONATION_EXIT_SUCCESS".
GET /api/me includes an impersonation field with the username of the original user while impersonation is active. From 2.43 it also includes canImpersonate: true when the current user is allowed to impersonate (feature enabled, required authority, and request from an allowed IP).
Logging in again in the same browser session ends impersonation.
How to use¶
- Enable the feature in
dhis.confand restart the server (see Configuration). - Log in as a user with the
ALLauthority or theF_IMPERSONATE_USERauthority. - Send
POST /api/auth/impersonate?username=<USERNAME>from the same session, for example:curl -b cookies.txt -c cookies.txt -X POST "https://<server>/api/auth/impersonate?username=<USERNAME>" - Use DHIS2 as the impersonated user.
- Send
POST /api/auth/impersonateExitto return to your own user.
Configuration¶
| Property | Description | Default |
|---|---|---|
switch_user_feature.enabled | Enables the feature. When disabled, both endpoints return 404. | off |
switch_user_allow_listed_ips | Comma-separated list of IP addresses from which impersonation requests are accepted. Values must match exactly; ranges/CIDR are not supported. | localhost,127.0.0.1,[0:0:0:0:0:0:0:1] (2.43 adds 0:0:0:0:0:0:0:1) |
Example:
switch_user_feature.enabled = on
switch_user_allow_listed_ips = 10.0.0.5
Important: reverse proxies
The allow-list is checked against the address of whatever connects directly to DHIS2. In most deployments that is a reverse proxy or load balancer, not the user's browser:
- If nginx or Apache runs on the same server (as in the recommended setup), every request appears to come from
127.0.0.1. Because127.0.0.1is in the default allow-list, every user passes the IP check once the feature is enabled.- In Docker or Kubernetes, requests appear to come from the proxy container or ingress address.
To restrict impersonation to specific client IPs, configure Tomcat to take the client IP from your proxy (see Reverse proxy → Passing the client IP to DHIS2), and only then add client IPs to the allow-list. Without this, the allow-list cannot distinguish users.
From 2.43, a rejected request returns
403 … not allowed to impersonate user from IP: <address>, which shows the address DHIS2 sees.
Security restrictions¶
- The feature is disabled by default.
- The user must have the
ALLorF_IMPERSONATE_USERauthority. - Requests must come from an allowed IP (see the note on reverse proxies above).
- Users without the
ALLauthority cannot impersonate a user who hasALL. - Users cannot impersonate themselves.
- An impersonated session cannot start a further impersonation unless the impersonated user has
F_IMPERSONATE_USER.
Logging¶
Each switch is logged as an AuthenticationSwitchUserEvent:
Authentication event: AuthenticationSwitchUserEvent; username: <impersonator>; targetUser: <impersonated user>
When exiting, username is the impersonated user and targetUser is the original user.