Manage Impersonation Sessions

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

This feature allows administrators to view active impersonation sessions, stop their current impersonation session, or manually revoke any impersonation session for security or administrative purposes. All session management actions are fully audited.

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

Viewing Active Sessions:

• Any user with impersonate_users permission: Can view all active impersonation sessions they have created.

Stopping a Session:

• Any user with an active impersonation token: Can stop their own impersonation session while using the impersonation token.

Revoking Sessions:

• Superadmin only: Can forcibly revoke any impersonation session, including sessions created by other administrators.

3. Business Rules & Enforcements

• Rule 1: Users can only view impersonation sessions they have created (except Superadmins who can revoke any session).
• Rule 2: Stopping a session requires using the impersonation token (validates that the caller is actually in an impersonation session).
• Rule 3: Revoking a session requires Superadmin global role.
• Rule 4: Once a session is stopped or revoked, the token cannot be used for any further requests (returns 401 REVOKED error).
• Rule 5: Stopped/revoked sessions remain in the database for audit purposes.
• Rule 6: All session management actions are logged with the reason (if provided).

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

Scenario A: Viewing all active impersonation sessions you created

1. Authenticate with your admin JWT token.
2. Send a GET request to /api/impersonate/active:

GET /api/impersonate/active
Authorization: Bearer {your_admin_jwt_token}

3. The API responds with a list of your active sessions:

[
  {
    "impersonation_id": "550e8400-e29b-41d4-a716-446655440000",
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "location": {
      "id": 5,
      "name": "Main Clinic"
    },
    "expires_at": "2026-03-31T14:30:00Z",
    "created_at": "2026-03-31T12:30:00Z",
    "last_used_at": "2026-03-31T13:15:00Z",
    "usage_count": 45
  }
]

---

Scenario B: Stopping an impersonation session (from within the session)

When to use: You are currently using an impersonation token and want to end the session gracefully.

1. While using the impersonation token, send a POST request to /api/impersonate/stop:

POST /api/impersonate/stop
Authorization: Bearer {impersonation_token}

{
  "reason": "Completed troubleshooting task"
}

Optional Fields:

• reason (string): Reason for stopping the session (max 500 characters, recommended for audit)
• impersonation_id (uuid): Session ID to stop (auto-detected if not provided)

2. The API responds with a success message:

{
  "message": "Impersonation session stopped successfully",
  "impersonation_id": "550e8400-e29b-41d4-a716-446655440000"
}

3. The impersonation token is now revoked and cannot be used for further requests.

---

Scenario C: Revoking an impersonation session (external revocation)

When to use:

• A Superadmin needs to forcibly terminate someone else’s impersonation session
• You need to revoke a session from outside the session (using your admin token)
• Security incident requires immediate session termination

Authorization Required: Superadmin global role

1. Authenticate with your Superadmin JWT token.
2. Obtain the impersonation_id from the active sessions list (see Scenario A).
3. Send a POST request to /api/impersonate/revoke:

POST /api/impersonate/revoke
Authorization: Bearer {your_admin_jwt_token}

{
  "impersonation_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Security audit - unauthorized access"
}

Required Fields:

• impersonation_id (uuid): The session ID to revoke

Optional Fields:

• reason (string): Reason for revocation (max 500 characters, highly recommended)

4. The API responds with a success message:

{
  "message": "Impersonation session revoked successfully",
  "impersonation_id": "550e8400-e29b-41d4-a716-446655440000"
}

5. The impersonation token is immediately revoked. Any subsequent requests with that token will receive a 401 error with code IMPERSONATION_TOKEN_REVOKED.

---

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

• Q: What’s the difference between stopping and revoking a session?

  • A:
    • Stop: Used from within an impersonation session (using the impersonation token). Anyone with the token can stop it. It’s the graceful way to end a session.
    • Revoke: Used from outside the session (using an admin token). Only Superadmins can revoke. It’s used for emergency termination or administrative control.

• Q: What happens if I try to revoke a session that doesn’t exist?

  • A: The API returns a 404 Not Found error with the message: “Impersonation session not found.”

• Q: What happens if I try to stop a session that’s already expired?

  • A: The middleware will detect the expired token and return a 401 error with code IMPERSONATION_TOKEN_EXPIRED before reaching the stop endpoint.

• Q: Can I revoke all impersonation sessions for a specific user at once?

  • A: This functionality exists in the service layer (ImpersonationService::revokeAllForUser()), but is not currently exposed via the API. It’s typically used internally when a user account is compromised or deactivated.

• Q: What information is logged when I stop or revoke a session?

  • A: The system logs: impersonation ID, impersonator ID and name, target user ID and name, action (stop/revoke), reason (if provided), who performed the action, IP address, and timestamp. The audit trail preserves this information even after token cleanup.

• Q: Can a stopped or revoked session be resumed?

  • A: No, once a session is stopped or revoked, it cannot be resumed. You must create a new impersonation session if needed.

---

Session States

An impersonation session can be in one of the following states:

Active

• Not revoked (revoked_at is NULL)
• Not expired (expires_at > current time)
• Can be used for API requests
• Will appear in the active sessions list

Expired

• Not revoked (revoked_at is NULL)
• Past expiration time (expires_at <= current time)
• Cannot be used for API requests (returns 401 EXPIRED)
• Remains in database for audit trail
• Will be deleted by cleanup command after 7 days (configurable)

Revoked

• Manually stopped or revoked (revoked_at is NOT NULL)
• Cannot be used for API requests (returns 401 REVOKED)
• Remains in database permanently for audit trail
• Records who revoked it and why

---

Audit Trail

All session management actions create audit log entries:

When viewing active sessions:

• No direct audit log (read operation)
• Access logged in standard API access logs

When stopping a session:

• Activity log: “Impersonation token modified” (revoked fields updated)
• Audit log: Records the stop action with reason
• Laravel log: Info-level entry with session details

When revoking a session:

• Activity log: “Impersonation token modified” (revoked fields updated)
• Audit log: Records the revoke action with reason and admin who revoked
• Laravel log: Warning-level entry (higher severity than stop)

See: Impersonation Audit Trail for comprehensive audit details.