docs/impersonation.md
# Impersonation
## Installation
1. The link to impersonate users is not available by default. To activate this tool, you need to set the `IMPERSONATION_URL` environment variable with the frontend URL where the auth params are taken and sent back to the server at `/api/v1/impersonations`. Additionally, you need to enable the `impersonation_tool` feature flag, which is already registered and can be activated via the admin panel.
2. Add `include API::Concerns::Impersonation::Hooks` to `app/controllers/api/v1/api_controller.rb` in order to set the `impersonated_by` attribute in the `current_user` and the `impersonated` header in the response.
## How does it work?
1. **Access Impersonation Link:**
- `AdminUser`s can find a link to impersonate users within the ActiveAdmin show page for users.
2. **Initiate Impersonation Request:**
- When an `AdminUser` clicks on the impersonation link, a request containing signed data is sent to a route specified by the `IMPERSONATION_URL` environment variable.
3. **Verify Data and Obtain Authentication Headers:**
- The designated route responsible for handling the signed data must make a POST request to `api/v1/impersonations`. This action retrieves the necessary authentication headers, including an additional header indicating that the headers are associated with an ongoing impersonation session. This extra header is named `impersonated`.
4. **Establish Impersonation Session:**
- With the obtained headers, the frontend is equipped to make requests to the server, effectively simulating the experience of being another user.
This workflow ensures a secure and seamless user impersonation process for `AdminUser`s. Adjust the configurations as needed based on your environment and requirements.
## Configuration
The signed data has a TTL of 5 minutes, to change this value update the `Impersonation::Verifier::EXPIRATION` constant.
Impersonated sessions have a TTL of 1 hour, to change this value update the lifespan at app/objects/impersonation/authenticator.rb
## Privacy and Security Considerations
### General Privacy and Sensitive Data
- Before using this tool check your compliance with GDPR, SOC-2, and other security standards concerning sensitive data.
### Policy Definition for User Impersonation
- Define policies that explicitly allow or disallow actions when using the user impersonation feature.
### Authentication Handling
- Authentication is managed by Devise. Admin users without a valid session cannot utilize the impersonation tool.
### Strong Permissions and Auditing Recommendations
- Ensure robust permissions and auditing mechanisms:
- Limit impersonation to specific roles, such as admins and the support team.
- Log every impersonation attempt, capturing details like the admin, the impersonated user, actions performed, and timestamps.
- Implement a clear indication in the UI when impersonation is active to avoid confusion. Consider using a banner or color change for visibility.
## Analytics Tool Integration
### General considerations
Before integrating a new Analitycs Tool, it's important to keep in mind that the impersonation feature can impact the metrics obtained.
Consider the actions that can be generated by a user who is impersonating, as the data may not accurately reflect real user activity.
Examples of affected indicators could include clicks and visits.