Django Impersonate

Common errors

• NoReverseMatch at /impersonate/...

  cause This usually indicates that the `impersonate.urls` are not correctly included in your project's `urls.py`, or there's a mismatch in how URL patterns are defined (e.g., using `url()` instead of `path()` for newer Django versions).
  fix Add `path('impersonate/', include('impersonate.urls'))` to your project's `urlpatterns` in `urls.py`. Also, ensure you are using `path()` if your Django version is 2.0 or higher.

• TypeError: __init__() missing 1 required positional argument: 'get_response' OR ImpersonateMiddleware not working as expected.

  cause This error or silent failure of the middleware typically means `ImpersonateMiddleware` is not properly placed in your `settings.MIDDLEWARE` list, or not listed at all.
  fix Ensure `impersonate.middleware.ImpersonateMiddleware` is present in your `settings.MIDDLEWARE` list, and crucially, that it comes *after* `django.contrib.sessions.middleware.SessionMiddleware` and `django.contrib.auth.middleware.AuthenticationMiddleware`.

• You do not have permission to impersonate users.

  cause The current user attempting to impersonate does not meet the required permissions. By default, only `is_superuser` users can impersonate.
  fix Log in as a superuser. If you want to allow non-superusers, set `IMPERSONATE_REQUIRE_SUPERUSER = False` in your `settings.py` and potentially define `IMPERSONATE_CUSTOM_USER_QUERY` to specify who can impersonate. You may also need to clear browser cookies after changing impersonation settings.

Warnings

• breaking Prior to version 1.7.0, django-impersonate used `django.conf.urls.url` for its URL patterns. Projects upgrading from older Django versions (pre-2.0) that also used `url()` in their project's `urls.py` would have been compatible. From 1.7.0 onwards, it uses `django.urls.path`. If your project's `urls.py` still uses `url()` and you upgrade django-impersonate to 1.7.0+, you might face `NoReverseMatch` errors or URL resolution issues if not updated to `path()`.
  Fix: Ensure your project's `urls.py` uses `django.urls.path` for including `impersonate.urls` and any other patterns, especially if your Django version is 2.0 or newer. Example: `path('impersonate/', include('impersonate.urls'))`.
• breaking In version 1.8.0, the `login_url` used for redirection after an unsuccessful impersonation attempt changed from a hardcoded `/accounts/login/` to dynamically using `django.conf.settings.LOGIN_URL`. If your project previously relied on the hardcoded path and did not have `LOGIN_URL` defined, this might cause unexpected redirection behavior.
  Fix: Ensure `settings.LOGIN_URL` is correctly configured in your Django project's `settings.py` to point to your desired login page, or define it if it was previously absent.
• gotcha The `ImpersonateMiddleware` must be placed correctly in your `MIDDLEWARE` setting. It relies on `SessionMiddleware` and `AuthenticationMiddleware` to function correctly, meaning it must appear *after* both of them in the `MIDDLEWARE` list.
  Fix: Verify that your `settings.MIDDLEWARE` list has `django.contrib.sessions.middleware.SessionMiddleware` and `django.contrib.auth.middleware.AuthenticationMiddleware` listed *before* `impersonate.middleware.ImpersonateMiddleware`.
• gotcha Impersonation links or buttons might not appear, or the impersonation functionality might not work as expected, due to incorrect user permissions or configuration. By default, only superusers can impersonate. You can change this behavior with `IMPERSONATE_REQUIRE_SUPERUSER` or `IMPERSONATE_CUSTOM_USER_QUERY`.
  Fix: Ensure the user attempting to impersonate is a superuser (or meets criteria defined by `IMPERSONATE_CUSTOM_USER_QUERY`). Check your `settings.py` for `IMPERSONATE_REQUIRE_SUPERUSER` (defaults to `True`) and `IMPERSONATE_CUSTOM_USER_QUERY` if you have custom permission logic.

Install

• pip install django-impersonate Install via pip

Imports

• ImpersonateMiddleware

  from impersonate.middleware import ImpersonateMiddleware

• impersonate_urls

  from django.urls import path, include
  
  urlpatterns = [
      path('impersonate/', include('impersonate.urls')),
      # ...
  ]

• impersonate_context_processor

  from impersonate.context_processors import impersonate

Quickstart

To quickly set up django-impersonate, add `impersonate` to `INSTALLED_APPS`, integrate `ImpersonateMiddleware` into your `MIDDLEWARE` stack (crucially, after `SessionMiddleware` and `AuthenticationMiddleware`), and include `impersonate.urls` in your project's `urls.py`. You can then use the provided views or template tags to initiate and end impersonation sessions. The quickstart demonstrates basic setup and how to include the URLs and middleware, along with template tag usage.

# settings.py
INSTALLED_APPS = [
    # ...
    'impersonate',
]

MIDDLEWARE = [
    # ...
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'impersonate.middleware.ImpersonateMiddleware', # Must be AFTER Session and Auth middleware
    # ...
]

# urls.py
from django.urls import path, include
from django.contrib import admin

urlpatterns = [
    path('admin/', admin.site.urls),
    path('impersonate/', include('impersonate.urls')),
    # ... your other urls
]

# In a template (e.g., base.html) to show an impersonation link:
# {% load impersonate_tags %}
# {% if user.is_authenticated and user.is_superuser %}
#   {% if impersonate %} # 'impersonate' variable comes from context processor
#     <a href="{% url 'impersonate-leave' %}">Leave Impersonation</a>
#   {% else %}
#     <a href="{% url 'impersonate-start' user_id=1 %}">Impersonate User (ID 1)</a> # Replace 1 with actual user ID
#     <a href="{% url 'impersonate-start' username='testuser' %}">Impersonate User (username testuser)</a>
#   {% endif %}
# {% endif %}