user_impersonate2

Note

This is a fork of Engine Yard's no-longer-maintained user_impersonate gem and is its official successor. It supports Rails from version 4.0 to Rails 5.1 (tests only exists for 4.0 though) and has been tested against Ruby 1.9.3, 2.0.0, 2.1.0, 2.2 and 2.3.1.

This fork also contains can_impersonate? functionality from https://github.com/DaveSanders/user_impersonate

Overview

user_impersonate2 allows staff users to impersonate normal users: to see what they see and to only do what they can do.

This concept and code was extracted from Engine Yard Cloud, which Engine Yard uses to support customer remotely.

This Rails engine currently supports the following Rails authentication systems:

• Devise

Links

• Wiki (includes tutorials etc.)

Example usage

When you are impersonating a user you see what they see with a header section above. By default, this will be red.

Installation

Add the gem to your Rails application's Gemfile and run bundle:

gem 'user_impersonate2', :require => 'user_impersonate'

Note that :require => 'user_impersonate' is required as this gem currently maintains the same internal directory structure as the original user_impersonate gem. This may change in future versions but is retained for compatibility for the time being.

Run the (sort of optional) generator:

bundle
rails generate user_impersonate

This adds the following line to your config/routes.rb file:

mount UserImpersonate::Engine => "/impersonate", as: "impersonate_engine"

It also generates a default initializer under config/initializers/user_impersonate2.rb.

Make sure that your layout files include the standard flashes since these are used to communicate information and error messages to the user:

<p class="notice"><%= flash[:notice] %></p>
<p class="alert"><%= flash[:error] %></p>

Next, add the impersonation header to your layouts:

<% if current_staff_user %>
  <%= render 'user_impersonate/header' %>
<% end %>

Next, add the "staff" concept to your User model.

To test the engine out, make all users staff!

# app/models/user.rb

def staff?
  true
end

# String to represent a user (e-mail, name, etc.)
def to_s
  email
end

You can now go to http://localhost:3000/impersonate to see the list of users, except your own user account. Click on the "Impersonate" link to impersonate that user and to see the magic!

Integration

To support this Rails engine, you need to add some things.

• current_user helper within controllers and helpers
• current_user.staff? - your User model needs a staff? method to identify if the current user is allowed to impersonate other users; if this method is missing, no user can access impersonation system
• current_user.can_impersonate?(user_id) - optional method on your User model that can be used to check permissions on whether this user can impersonate a specific user

User#staff?

One way to add the staff? helper is to add a column to your User model:

rails generate migration add_staff_to_users staff:boolean
rake db:migrate db:test:prepare

User#can_impersonate?(user_id)

This method allows you to create logic to decide whether one user can impersonate another. For example, you may have a customer service rep who can impersonate users, but not administrators. This method will get passed the user_id that is to be impersonated, but the logic is up to you to decide. For example:

def can_impersonate?(user_id)
  target_user = User.find(user_id)
  return false if self.role == 'customer service' && target_user.role == 'admin'
  true
end

Note that this method is optional. If you don't want to limit who can impersonate whom, then simply don't declare the method in your configuration.

Customization

Header

You can override the bright red header by creating a app/views/user_impersonate/_header.html.erb file (or whatever template system you like).

The app/views/user_impersonate/_header.html.haml HAML partial for this header would be:

%div#impersonating
  .impersonate-controls.page
    .impersonate-info.grid_12
      You (
      %span.admin_name= current_staff_user
      ) are impersonating
      %span.user_name= link_to current_user, url_for([:admin, current_user])
      ( User id:
      %span.user_id= current_user.id
      )
      - if current_user.no_accounts?
        ( No accounts )
      - else
        ( Account name:
        %span.account_id= link_to current_user.accounts.first, url_for([:admin, current_user.accounts.first])
        , id:
        %strong= current_user.accounts.first.id
        )
    .impersonate-buttons.grid_12
      = form_tag url_for([:ssh_key, :admin, current_user]), :method => "put" do
        %span Support SSH Key
        = select_tag 'public_key', options_for_select(current_staff_user.keys.map {|k| k})
        %button{:type => "submit"} Install SSH Key
      or
      = form_tag [:admin, :revert], :method => :delete, :class => 'revert-form' do
        %button{:type => "submit"} Revert to admin

Redirects

By default, when you impersonate and when you stop impersonating a user you are redirected to the root URL.

Alternative paths can be configured in the initializer config/initializers/user_impersonate.rb created by the user_impersonate generator described above.

# config/initializers/user_impersonate.rb
module UserImpersonate
  class Engine < Rails::Engine
    config.redirect_on_impersonate = '/'
    config.redirect_on_revert = '/impersonate'
  end
end

User model and lookup

By default, user_impersonate2 assumes the user model is named User, that you use User.find(id) to find a user given its ID, use some_user.id to get the related ID value and that your user model has a staff? attribute that returns true if the corresponding user is staff and false otherwise.

You can change this default behaviour in the initializer config/initializers/user_impersonate.rb.

# config/initializers/user_impersonate.rb
module UserImpersonate
  class Engine < Rails::Engine
    config.user_class                  = "User"
    config.user_finder                 = "find"   # User.find
    config.user_id_column              = "id"     # Such that User.find(aUser.id) works
    config.user_is_staff_method        = "staff?" # current_user.staff?
    config.user_can_impersonate_method = nil # current_user.can_impersonate?(user_id)
  end
end

By default, user_impersonate2 will use the same model for staff/admin users as that described above for regular users. Some configurations, using frameworks such as Active Admin, for example, use a different model for staff/admin users. user_impersonate2's default behaviour can be overridden using the following initializer settings:

# config/initializers/user_impersonate.rb
module UserImpersonate
  class Engine < Rails::Engine
    # For Active Admin "AdminUser" model, use 'authenticate_admin_user!'
    config.authenticate_user_method = 'authenticate_admin_user!'

    # For Active Admin "AdminUser" model, use 'AdminUser'
    config.staff_class = 'AdminUser'

    # Staff user model lookup method
    config.staff_finder = 'find'

    # For Active Admin "AdminUser" model, use 'current_admin_user'
    config.current_staff = 'current_admin_user'
  end
end

Spree-specific stuff

Modify User and add a current_user helper:

Spree::User.class_eval do
  def staff?
    has_spree_role?('admin')
  end

  def to_s
    email
  end
end

ApplicationController.class_eval do
  helper_method :current_user
  def current_user
    spree_current_user
  end
end

Use the following initializer:

# config/initializers/user_impersonate.rb
module UserImpersonate
  class Engine < Rails::Engine
    config.user_class = 'Spree::User'
    config.user_finder = 'find'
    config.user_id_column = 'id'
    config.user_is_staff_method = 'staff?'
    config.authenticate_user_method = 'authenticate_spree_user!'
    config.redirect_on_impersonate = '/'
    config.redirect_on_revert = '/'
    config.user_name_column = 'users'
  end
end

Use deface to add the header:

Deface::Override.new(:virtual_path => "spree/layouts/spree_application",
                     :name => "impersonate_header", 
                     :insert_before => "div.container",
                     :text => "<% if current_staff_user %><%= render 'user_impersonate/header' %><% end %>")

Contributing

See .travis.yml for details of the commands that are run as part of the Travis-CI build of this project. The minimum bar for all push requests is that the Travis-CI build must pass. Contributors are also strongly encouraged to add new tests to cover any new functionality introduced into the gem.

Installing gem dependencies via Bundler

To install all gem dependencies for the active version of Ruby and for a given gemfile, you'll need to run the bundle command, e.g.

BUNDLE_GEMFILE=Gemfile.rails4 bundle

Running tests against all configurations (requires rbenv)

To run tests against all configurations specified in the Travis-CI configuration file, run script/test-all:

script/test-all

This scripts requires that you have rbenv installed along with all required versions of Ruby. Furthermore, you'll need to make sure that each version of Ruby installed via rbenv has all the required gems available to it installed using the bundle command.

Running tests against a single configuration

To manually run the Travis-CI verification steps on your local machine, you can use the following sequence of commands for Rails 4.0.x:

script/test -g Gemfile.rails4

script/test takes care of running Bundler to update any gem dependencies, setting up the database, running all tests and then performing a test build of the gem in order to catch any syntax errors.

Licence

user_impersonate2 is released under the MIT licence.