Skip to content

Latest commit

 

History

History
55 lines (34 loc) · 3.31 KB

impersonation.md

File metadata and controls

55 lines (34 loc) · 3.31 KB
Raw

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:

    • AdminUsers 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 AdminUsers. 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.