feat(admin): add user impersonation feature #366

qdaxb · 2025-12-09T05:55:23Z

Summary

Add admin impersonation feature allowing administrators to impersonate users for troubleshooting
Implements a secure authorization workflow requiring explicit user consent
Includes full audit logging of all actions during impersonation sessions

Changes

Backend

Models: Add ImpersonationRequest and ImpersonationAuditLog tables
Schemas: Add Pydantic schemas for impersonation API requests/responses
Service: Add ImpersonationService for request lifecycle management
Security: Extend JWT handling to support impersonation tokens with additional claims
API Routes:
- Admin endpoints: create request, list requests, cancel, start session, exit, audit logs
- Public endpoints: get confirm info, approve request, reject request
Migration: Add Alembic migration for new database tables

Frontend

Types: Add TypeScript types for impersonation feature
API Client: Add impersonation API client methods
Components:
- ImpersonationBanner: Shows warning banner during active impersonation
- ImpersonateDialog: Dialog for creating impersonation requests
UserContext: Extended with impersonation state and exit function
UserList: Added impersonate button to user management
Confirmation Page: /impersonate/confirm/[token] for user authorization
i18n: Added English and Chinese translations

Security Features

Authorization Required: Target user must explicitly approve the request
Time-Limited Links: Authorization links expire after 30 minutes
Session Expiry: Impersonation sessions auto-expire after 24 hours
Audit Trail: All API actions during impersonation are logged
Visual Indicator: Clear warning banner shown during active impersonation

Test Plan

Admin can create impersonation request for any active user
Confirmation link is generated and can be copied
Target user receives link and can view request details
Target user can approve or reject the request
Admin can start session after approval
Impersonation banner appears during active session
Admin can exit impersonation and return to their account
Expired requests are handled correctly
Audit logs are recorded for all actions during impersonation

Summary by CodeRabbit

Release Notes

New Features
- Impersonation request workflow enabling temporary user account access with token-based confirmation
- Automatic session expiry with real-time countdown timers
- Audit logs tracking all impersonation activities
- Admin interface for managing impersonation requests and sessions
- Impersonation status banner with exit controls during active sessions

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add a new admin feature allowing administrators to impersonate users for troubleshooting purposes. The feature requires explicit user authorization before the impersonation session can begin. Backend changes: - Add ImpersonationRequest and ImpersonationAuditLog models - Add Pydantic schemas for impersonation API - Add impersonation service with request lifecycle management - Extend security.py with impersonation JWT token support - Add admin API routes for managing impersonation requests - Add public confirmation API routes for user authorization - Add Alembic migration for new tables Frontend changes: - Add TypeScript types for impersonation - Add impersonation API client - Add ImpersonationBanner component for active session indicator - Extend UserContext with impersonation state management - Add ImpersonateDialog component for creating requests - Add impersonate button to UserList component - Add user confirmation page at /impersonate/confirm/[token] - Add i18n translations (en/zh-CN) Security features: - User must explicitly approve impersonation requests - Authorization links expire after 30 minutes - Sessions expire after 24 hours - All impersonation actions are logged for audit

coderabbitai · 2025-12-09T05:55:33Z

Walkthrough

This PR implements a complete impersonation feature enabling admins to temporarily assume the identity of target users. It includes database models, API endpoints for creation/approval/session management, a service layer with validation and audit logging, token-based authentication handlers, and comprehensive frontend UI with confirmation dialogs, banners, and status tracking.

Changes

Cohort / File(s)	Summary
Database & Migrations `backend/alembic/versions/add_impersonation_tables.py`	Adds Alembic migration creating `impersonation_requests` and `impersonation_audit_logs` tables with foreign keys, indexes, and MySQL-specific configuration.
Backend Models `backend/app/models/impersonation.py`, `backend/app/models/__init__.py`	Introduces SQLAlchemy models `ImpersonationRequest` (with admin/target user relationships, token, status, expiry) and `ImpersonationAuditLog` (audit trail with action, method, path, IP, user-agent). Exports both in `__init__.py`.
Backend Schemas `backend/app/schemas/impersonation.py`	Defines Pydantic schemas: request/response DTOs, confirmation info, session start/exit payloads, audit log models, and status literals ("pending", "approved", "rejected", "expired", "used").
Backend Service `backend/app/services/impersonation_service.py`	Provides `ImpersonationService` singleton with full workflow: create, approve, reject, cancel requests; session lifecycle; expiry/cleanup; audit logging with sensitive data redaction; and confirmation URL generation.
Backend Security `backend/app/core/security.py`	Adds token lifecycle helpers: `create_impersonation_token()`, `verify_impersonation_token()`, `get_current_user_with_impersonation_info()`, and `get_impersonation_info_from_request()` for JWT-based impersonation context propagation.
Backend API Endpoints `backend/app/api/api.py`, `backend/app/api/endpoints/impersonation.py`, `backend/app/api/endpoints/impersonate_confirm.py`	Registers impersonation routes; implements admin endpoints (create, list, get, cancel, start session, exit, audit logs) and public confirmation endpoints (get info, approve, reject).
Frontend Types `frontend/src/types/impersonation.ts`	Defines TypeScript interfaces for requests, responses, audit logs, statuses, and JWT-derived impersonation context.
Frontend API Client `frontend/src/apis/impersonation.ts`	Exports `impersonationApis` wrapper with methods for admin workflows, confirmation endpoints, and audit log retrieval.
Frontend Context & State `frontend/src/features/common/UserContext.tsx`	Extends `UserContext` with impersonation state (flag, impersonator name, expiry, exit function); adds token parsing and exit session handler.
Frontend Components `frontend/src/components/common/ImpersonationBanner.tsx`, `frontend/src/features/admin/components/ImpersonateDialog.tsx`, `frontend/src/features/admin/components/UserList.tsx`	Adds banner (displays impersonation status and countdown), dialog (manages request creation/approval flow), and integrates impersonation button into user list.
Frontend Pages `frontend/src/app/impersonate/confirm/[token]/page.tsx`	New page for public confirmation link; displays request details, authentication check, approve/reject actions, and countdown timer.
Frontend Translations `frontend/src/i18n/locales/en/admin.json`, `frontend/src/i18n/locales/zh-CN/admin.json`	Adds English and Chinese localization for impersonation UI strings (dialog, banner, status labels, error messages).

Sequence Diagram(s)

sequenceDiagram
    actor Admin
    participant Frontend
    participant Backend API
    participant DB
    participant Mail/Link
    participant TargetUser

    Admin->>Frontend: Click impersonate user
    Frontend->>Backend API: POST /admin/impersonation/requests (target_user_id)
    Backend API->>DB: Create ImpersonationRequest (pending, token, expiry)
    DB-->>Backend API: Request created
    Backend API-->>Frontend: {token, confirmation_url, status: pending}
    Frontend->>Frontend: Display dialog with confirmation link
    
    alt Admin Shares Link
        Frontend->>Mail/Link: Email/Copy confirmation_url
        Mail/Link->>TargetUser: Receive confirmation link
    end
    
    TargetUser->>Frontend: Open confirmation link
    Frontend->>Backend API: GET /impersonate/confirm/{token}
    Backend API->>DB: Query ImpersonationRequest
    DB-->>Backend API: Request details + remaining_seconds
    Backend API-->>Frontend: {status: pending, admin_name, remaining_seconds}
    Frontend->>Frontend: Show approval/rejection options
    
    alt TargetUser Approves
        TargetUser->>Frontend: Click Approve
        Frontend->>Backend API: POST /impersonate/confirm/{token}/approve (authenticated)
        Backend API->>DB: Update ImpersonationRequest (approved_at, session_expires_at)
        DB-->>Backend API: Updated request
        Backend API-->>Frontend: {status: approved, access_token, impersonated_user_id}
        Frontend->>Frontend: Store impersonation token
    else TargetUser Rejects
        TargetUser->>Frontend: Click Reject
        Frontend->>Backend API: POST /impersonate/confirm/{token}/reject
        Backend API->>DB: Update ImpersonationRequest (status: rejected)
        DB-->>Backend API: Updated request
        Backend API-->>Frontend: {status: rejected}
    end

sequenceDiagram
    actor Admin
    participant Frontend
    participant Backend API
    participant DB
    participant Security

    Admin->>Frontend: (In approved state, click Start Session)
    Frontend->>Backend API: POST /admin/impersonation/sessions (request_id)
    Backend API->>DB: Fetch ImpersonationRequest (verify approved status)
    DB-->>Backend API: Request details
    
    alt Session Valid
        Backend API->>Security: create_impersonation_token(admin_user, target_user, expiry)
        Security-->>Backend API: JWT with impersonation metadata
        Backend API->>DB: Update ImpersonationRequest (status: used)
        Backend API->>DB: Log audit event (action: session_started)
        DB-->>Backend API: Logged
        Backend API-->>Frontend: {access_token, impersonated_user_id, session_expires_at}
        Frontend->>Frontend: Store token in localStorage
        Frontend->>Frontend: Update UserContext (isImpersonating: true)
        Frontend->>Frontend: Banner appears with countdown
        Frontend->>Frontend: Page reloads/redirects
    else Session Expired
        Backend API-->>Frontend: Error (session expired)
    end
    
    Admin->>Frontend: (While impersonating, click Exit)
    Frontend->>Backend API: POST /admin/impersonation/sessions/exit
    Backend API->>Security: verify_impersonation_token(token)
    Security-->>Backend API: Impersonation metadata (admin_user_id)
    Backend API->>Security: create_token(admin_user)
    Security-->>Backend API: New admin JWT
    Backend API->>DB: Log audit event (action: session_exited)
    Backend API-->>Frontend: {access_token (admin token), message}
    Frontend->>Frontend: Clear impersonation token
    Frontend->>Frontend: Update UserContext (isImpersonating: false)
    Frontend->>Frontend: Store admin token, navigate to /admin

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Areas requiring extra attention:

Security token handling (backend/app/core/security.py): Verify JWT payload structure, expiration validation, and that impersonation claims cannot be forged or replayed.
Service layer logic (backend/app/services/impersonation_service.py): Validate expiry checks, approval state transitions, sensitive data redaction strategy, and audit log sanitization correctness.
API endpoint access control (backend/app/api/endpoints/impersonation.py, impersonate_confirm.py): Ensure admin-only endpoints properly check authorization and public confirmation endpoints have appropriate rate-limiting/token validation.
Frontend token persistence and parsing (frontend/src/features/common/UserContext.tsx): Verify safe JWT decoding, impersonation state reset on exit, and proper cleanup of tokens.
Database migration (backend/alembic/versions/add_impersonation_tables.py): Confirm foreign key constraints, index efficiency, and cross-database compatibility (SQLite/MySQL).

Possibly related PRs

Wegent#268: Modifies backend/app/api/api.py to register new APIRouter endpoints (similar pattern for adding impersonation routes).

Suggested reviewers

feifei325

Poem

🐰✨ A feature hops in with tokens so bright,
Admins now masquerade, with banners in sight!
Confirm and approve, with countdown so fair,
Exit with grace—back to roots, if you dare! 🎭

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(admin): add user impersonation feature' directly and clearly describes the main change—adding a user impersonation capability to the admin panel.
Docstring Coverage	✅ Passed	Docstring coverage is 91.18% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch wegent/admin-impersonate-user-login

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/i18n/locales/en/admin.json (1)
15-22: Missing close translation key in common section.

The ImpersonateDialog.tsx component references t('common.close') at line 292, but this key is not defined in the common section. Only cancel, create, save, delete, reset, and loading are present.

Add the missing translation:
   "common": {
     "cancel": "Cancel",
+    "close": "Close",
     "create": "Create",
     "save": "Save",
     "delete": "Delete",
     "reset": "Reset",
     "loading": "Loading..."
   },

🧹 Nitpick comments (14)

backend/alembic/versions/add_impersonation_tables.py (1)
65-67: Redundant indexes on primary key columns.

The ix_impersonation_requests_id and ix_impersonation_audit_logs_id indexes are unnecessary since the id columns are already primary keys, which automatically creates a unique index.

Consider removing these redundant index operations:
-    # Create indexes for impersonation_requests
-    op.create_index(
-        "ix_impersonation_requests_id", "impersonation_requests", ["id"], unique=False
-    )
     op.create_index(
         "ix_impersonation_requests_admin_user_id",
-    # Create indexes for impersonation_audit_logs
-    op.create_index(
-        "ix_impersonation_audit_logs_id", "impersonation_audit_logs", ["id"], unique=False
-    )
     op.create_index(
         "ix_impersonation_audit_logs_request_id",
And corresponding removals in the downgrade() function.

Also applies to: 125-127
backend/app/core/security.py (3)
216-249: Ensure timezone-aware datetime for token expiration.

The session_expires_at parameter is used directly as the JWT exp claim. If the caller passes a naive datetime, JWT validation may behave unexpectedly depending on the server's timezone.

Consider ensuring timezone awareness:
 def create_impersonation_token(
     target_user: User,
     admin_user: User,
     impersonation_request_id: int,
     session_expires_at: datetime,
 ) -> str:
     from datetime import timezone

+    # Ensure timezone-aware expiration
+    if session_expires_at.tzinfo is None:
+        session_expires_at = session_expires_at.replace(tzinfo=timezone.utc)
+
     to_encode = {
         "sub": target_user.user_name,
289-290: Preserve exception chain for better debugging.

Per static analysis hint, use raise ... from to maintain the exception chain.
-    except JWTError:
-        raise credentials_exception
+    except JWTError as err:
+        raise credentials_exception from err
336-341: Preserve exception chain here as well.
-    except JWTError:
-        raise HTTPException(
+    except JWTError as err:
+        raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Could not validate credentials",
             headers={"WWW-Authenticate": "Bearer"},
-        )
+        ) from err
backend/app/models/__init__.py (1)
18-26: Consider sorting __all__ alphabetically.

Per static analysis and isort conventions, the __all__ list should be sorted.
 __all__ = [
+    "ImpersonationAuditLog",
+    "ImpersonationRequest",
+    "Kind",
+    "SharedTeam",
+    "SkillBinary",
+    "Subtask",
     "User",
-    "Kind",
-    "Subtask",
-    "SharedTeam",
-    "SkillBinary",
-    "ImpersonationRequest",
-    "ImpersonationAuditLog",
 ]
frontend/src/features/admin/components/ImpersonateDialog.tsx (2)
82-89: Potential infinite re-creation loop due to createRequest dependency.

The createRequest callback is recreated whenever targetUser, toast, t, or onClose changes. Since it's in the dependency array of this useEffect, and createRequest sets state (setRequest), this could cause unintended behavior if any of these dependencies change while the dialog is open.

Consider using a ref to track if the request has already been created for the current dialog session:
+  const requestCreatedRef = useRef(false);
+
   // Create request when dialog opens
   useEffect(() => {
     if (isOpen && targetUser) {
+      if (requestCreatedRef.current) return;
+      requestCreatedRef.current = true;
       createRequest();
     } else {
       setRequest(null);
       setCopied(false);
+      requestCreatedRef.current = false;
     }
-  }, [isOpen, targetUser, createRequest]);
+  }, [isOpen, targetUser]);
165-178: Consider showing error toast if cancel fails.

The cancel handler silently logs errors but still closes the dialog. While this UX is acceptable, users might want feedback if the cancellation didn't actually succeed on the server.
     try {
       await impersonationApis.cancelRequest(request.id);
       toast({ title: t('impersonation.request_cancelled') });
     } catch (error) {
       console.error('Failed to cancel request:', error);
+      toast({
+        variant: 'destructive',
+        title: 'Failed to cancel request',
+      });
     }
     onClose();
backend/app/models/impersonation.py (1)
52-83: Consider adding direct user relationships for query efficiency.

The ImpersonationAuditLog model stores admin_user_id and target_user_id but only has a relationship to ImpersonationRequest. In the endpoint code (lines 259-261 in impersonation.py), user names are fetched via log.impersonation_request.admin_user.user_name, which requires traversing multiple relationships and could cause N+1 query issues when listing logs.

Consider adding direct relationships:
     # Relationships
     impersonation_request = relationship(
         "ImpersonationRequest", backref="audit_logs"
     )
+    admin_user = relationship(
+        "User", foreign_keys=[admin_user_id]
+    )
+    target_user = relationship(
+        "User", foreign_keys=[target_user_id]
+    )
backend/app/api/endpoints/impersonation.py (1)
252-270: Potential N+1 query issue when building audit log responses.

Each log item accesses log.impersonation_request.admin_user.user_name and log.impersonation_request.target_user.user_name, which can trigger additional queries per log entry. Consider eager loading these relationships in the service layer or adding direct relationships to the ImpersonationAuditLog model.

In the service layer's list_audit_logs method, add eager loading:
from sqlalchemy.orm import joinedload

query = db.query(ImpersonationAuditLog).options(
    joinedload(ImpersonationAuditLog.impersonation_request)
    .joinedload(ImpersonationRequest.admin_user),
    joinedload(ImpersonationAuditLog.impersonation_request)
    .joinedload(ImpersonationRequest.target_user),
)
backend/app/schemas/impersonation.py (1)

26-44: Consider excluding token from response in certain contexts.

The ImpersonationRequestResponse includes the full token field. While this is needed for generating the confirmation URL, consider whether the raw token should be exposed in all API responses, as it could potentially be logged or leaked. The confirmation URL itself is sufficient for the user flow.

If you want to limit token exposure, you could create a separate response schema without the token field for list operations, or ensure the token is only returned during creation.
backend/app/services/impersonation_service.py (4)
29-42: Add ClassVar annotation and handle invalid environment variable values.

Two issues with class attributes:

SENSITIVE_FIELDS is a mutable class attribute that should be annotated with ClassVar (per static analysis hint RUF012).

int(os.getenv(...)) will raise ValueError at import time if the environment variable is set to a non-numeric string.
+from typing import Any, ClassVar, Dict, List, Optional, Tuple
-from typing import Any, Dict, List, Optional, Tuple

 class ImpersonationService:
     """Service for managing impersonation requests and sessions."""

     # Configuration with environment variable support
-    REQUEST_EXPIRY_MINUTES = int(os.getenv("IMPERSONATION_REQUEST_EXPIRY_MINUTES", "30"))
-    SESSION_EXPIRY_HOURS = int(os.getenv("IMPERSONATION_SESSION_EXPIRY_HOURS", "24"))
-    AUDIT_RETENTION_DAYS = int(os.getenv("IMPERSONATION_AUDIT_RETENTION_DAYS", "30"))
+    REQUEST_EXPIRY_MINUTES: ClassVar[int] = int(
+        os.getenv("IMPERSONATION_REQUEST_EXPIRY_MINUTES", "") or "30"
+    )
+    SESSION_EXPIRY_HOURS: ClassVar[int] = int(
+        os.getenv("IMPERSONATION_SESSION_EXPIRY_HOURS", "") or "24"
+    )
+    AUDIT_RETENTION_DAYS: ClassVar[int] = int(
+        os.getenv("IMPERSONATION_AUDIT_RETENTION_DAYS", "") or "30"
+    )

     # Sensitive fields to redact in audit logs
-    SENSITIVE_FIELDS = [
+    SENSITIVE_FIELDS: ClassVar[List[str]] = [
         "password",
278-313: Consider adding expiration check for consistency with approve_request.

The approve_request method checks for expiration (lines 258-265) and updates status to "expired" if the request has expired. However, reject_request lacks this check, allowing rejection of already-expired requests.
         # Check request status
         if request.status != "pending":
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail=f"Request is already {request.status}",
             )

+        # Check expiration
+        if request.expires_at < datetime.now(timezone.utc):
+            request.status = "expired"
+            db.commit()
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Request has expired",
+            )
+
         # Reject the request
         request.status = "rejected"
551-562: Consider using settings for consistent configuration access.

The settings object is imported (line 20) but not used. FRONTEND_URL should come from settings for centralized configuration management rather than directly from os.getenv.
     def get_confirmation_url(self, token: str) -> str:
         """
         Generate confirmation URL for impersonation request.

         Args:
             token: Request token

         Returns:
             Confirmation URL
         """
-        frontend_url = os.getenv("FRONTEND_URL", "http://localhost:3000")
+        frontend_url = getattr(settings, "FRONTEND_URL", "http://localhost:3000")
         return f"{frontend_url}/impersonate/confirm/{token}"
Alternatively, add FRONTEND_URL to your settings configuration class if not already present.

162-198: Consider adding bounds validation for pagination parameters.

If page < 1 or limit <= 0 is passed, the offset calculation (page - 1) * limit could produce unexpected results (negative offset or zero/negative limit). While the API layer may validate these, defensive validation here would prevent misuse.
     def list_requests(
         self,
         db: Session,
         admin_user_id: int,
         page: int = 1,
         limit: int = 20,
         status_filter: Optional[str] = None,
     ) -> Tuple[List[ImpersonationRequest], int]:
+        page = max(1, page)
+        limit = max(1, min(limit, 100))  # Cap at reasonable maximum

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 744f5d5 and 86ec04f.

📒 Files selected for processing (18)

backend/alembic/versions/add_impersonation_tables.py (1 hunks)
backend/app/api/api.py (2 hunks)
backend/app/api/endpoints/impersonate_confirm.py (1 hunks)
backend/app/api/endpoints/impersonation.py (1 hunks)
backend/app/core/security.py (2 hunks)
backend/app/models/__init__.py (2 hunks)
backend/app/models/impersonation.py (1 hunks)
backend/app/schemas/impersonation.py (1 hunks)
backend/app/services/impersonation_service.py (1 hunks)
frontend/src/apis/impersonation.ts (1 hunks)
frontend/src/app/impersonate/confirm/[token]/page.tsx (1 hunks)
frontend/src/components/common/ImpersonationBanner.tsx (1 hunks)
frontend/src/features/admin/components/ImpersonateDialog.tsx (1 hunks)
frontend/src/features/admin/components/UserList.tsx (5 hunks)
frontend/src/features/common/UserContext.tsx (4 hunks)
frontend/src/i18n/locales/en/admin.json (1 hunks)
frontend/src/i18n/locales/zh-CN/admin.json (1 hunks)
frontend/src/types/impersonation.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (21)

frontend/src/i18n/**/*.{ts,tsx,json}