Start Impersonation Session

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

This feature allows authorized administrators to initiate an impersonation session to access the application as another user. The administrator receives a temporary JWT token that grants them access to act as the target user within a specific location context.

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

• Superadmin: Can impersonate any active user in any active location.
• Users with impersonate_users permission: Can impersonate users if they have the global impersonate_users permission.

Required Permission: impersonate_users (global scope)

3. Business Rules & Enforcements

• Rule 1: The impersonator must have the impersonate_users global permission.
• Rule 2: The target user ID must be different from the impersonator’s ID (no self-impersonation).
• Rule 3: The target user must have ACTIVE status.
• Rule 4: The specified location must have ACTIVE status.
• Rule 5: The target user must have active access to the specified location.
• Rule 6: The TTL (time-to-live) must be between 1 minute and 1440 minutes (24 hours). Default is 60 minutes.
• Rule 7: Token scopes must be from the allowed list: impersonation, read_only, limited (currently only impersonation is implemented).

4. UI Placement

API Endpoint: POST /api/impersonate/start

This endpoint is typically called from administrative tools or support interfaces.

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

Scenario: Starting an impersonation session

1. Authenticate as an administrator with the impersonate_users permission.
2. Send a POST request to /api/impersonate/start with the following payload:

{
  "user_id": 123,
  "location": 5,
  "ttl_minutes": 120,
  "reason": "Troubleshooting reported issue with BIP access"
}

Required Fields:

• user_id (integer): The ID of the user to impersonate
• location (integer): The location ID for the impersonation context

Optional Fields:

• ttl_minutes (integer): Token lifetime in minutes (default: 60, min: 1, max: 1440)
• reason (string): Reason for impersonation (max 500 characters, recommended for audit purposes)

3. Include your admin JWT token in the Authorization header:

Authorization: Bearer {your_admin_jwt_token}

4. The API will respond with:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "impersonation_id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2026-03-31T14:30:00Z",
  "expires_in": 7200,
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "roles": ["..."],
    "permissions": ["..."]
  },
  "impersonator": {
    "id": 1,
    "name": "Admin User",
    "email": "admin@example.com"
  }
}

5. Store the token value securely. Use this token in subsequent API requests to act as the target user.

6. Use the impersonation token in the Authorization header for subsequent requests:

Authorization: Bearer {impersonation_token}

7. The system will respond with custom headers indicating active impersonation:

X-Impersonation-Active: true
X-Impersonation-ID: 550e8400-e29b-41d4-a716-446655440000
X-Effective-User-ID: 123

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

• Q: What happens if I try to impersonate a user who doesn’t have access to the specified location?

  • A: The API will return a 400 Bad Request error with the message: “Target user does not have active access to the specified location.”

• Q: What happens if I try to impersonate myself?

  • A: The API will return a 400 Bad Request error with the message: “You cannot impersonate yourself.”

• Q: What happens if the target user becomes inactive after I start the session?

  • A: Your active session continues until the token expires or is stopped/revoked. However, new impersonation sessions cannot be created for inactive users.

• Q: Can I extend an active impersonation session?

  • A: No, you cannot extend an existing session. When the token expires, you must create a new impersonation session. The maximum TTL is 24 hours (1440 minutes).

• Q: What information is logged when I start an impersonation session?

  • A: The system logs: impersonator ID and name, target user ID and name, location ID, impersonation ID (UUID), TTL, reason (if provided), IP address, user agent, and timestamp. All actions performed during the session are also logged with both actor and effective user information.

• Q: What permissions does the impersonation token have?

  • A: The impersonation token inherits all the roles and permissions that the target user has for the specified location. The response includes the target user’s location-scoped roles and permissions.

---

Technical Details

JWT Token Structure

The impersonation token is a JWT with the following custom claims:

{
  "sub": 123,                    // Target user ID
  "impersonator_id": 1,          // Impersonator user ID
  "impersonation_id": "uuid",    // Unique session identifier
  "scopes": ["impersonation"],   // Token scopes
  "type": "impersonation",       // Token type marker
  "iat": 1711888800,             // Issued at timestamp
  "exp": 1711892400              // Expiration timestamp
}

Token Storage

• The JWT token is hashed using SHA-256 before storage
• Only the hash is stored in the database (not the plain token)
• The token hash is indexed for fast lookup during validation

Security Measures

1. Permission Check: Validates impersonate_users permission before allowing session creation
2. Business Rule Validation: Enforces all business rules (active user, active location, TTL bounds, etc.)
3. Unique Session ID: Each session has a unique UUID to prevent token confusion
4. Token Hash Storage: Only hashes stored in database, not plain tokens
5. Comprehensive Logging: All actions recorded in multiple audit tables
6. IP and User Agent Tracking: Records client information for security analysis