user_impersonate 0.7.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# User Impersonate
+
+Allow staff users to impersonate your normal users: see what they see, only do what they can do.
+
+This concept and code was extracted from [Engine Yard Cloud](http://www.engineyard.com/products/cloud), which we use when we want to help support a customer remotely.
+
+This Rails engine currently supports the following Rails authentication systems:
+
+* [Devise](https://github.com/plataformatec/devise)
+
+## Example usage
+
+When you are impersonating a user you see what they see, with a header section above:
+
+<img src="https://img.skitch.com/20120919-c8382rgdcub7gsh2p82k8reng3.png" alt="Impersonating a user" />
+
+## Installation
+
+Add the gem to your Rails application's Gemfile and run `bundle`:
+
+``` ruby
+gem "user_impersonate"
+```
+
+Run the (sort of optional) generator:
+
+```
+bundle
+rails g user_impersonate
+```
+
+This adds the following line within your `config/routes.rb`:
+
+``` ruby
+mount UserImpersonate::Engine => "/impersonate", as: "impersonate_engine"
+```
+
+Include in your layout files support for `flash[:error]` and `flash[:notice]`, such as:
+
+``` erb
+<p class="notice"><%= flash[:notice] %></p>
+<p class="alert"><%= flash[:error] %></p>
+```
+
+Next, add the impersonation header to your layouts:
+
+``` erb
+<% if current_staff_user %>
+  <%= render 'user_impersonate/header' %>
+<% end %>
+```
+
+Next, add staff concept to your User model.
+
+To test the engine out, make all users staff!
+
+``` ruby
+# app/models/user.rb
+
+def staff?
+  true
+end
+
+# String to represent a user (email, name, etc)
+def to_s
+  email
+end
+```
+
+You can now go to [http://localhost:3000/impersonate](http://localhost:3000/impersonate) to see the list of users, except your own user account. If you impersonate one you will see the magic!
+
+## Integration
+
+To support this Rails engine, you need to add some things.
+
+* `current_user` helper within controllers & helpers
+* `current_user.staff?` - your `User` model needs a `staff?` to identify if the current user is allowed to impersonate other users; if missing, no user can access impersonation system
+
+### User#staff?
+
+One way to add this helper is to add a column to your User model:
+
+```
+rails g migration add_staff_flag_to_users staff:boolean
+rake db:migrate db:test:prepare
+```
+
+## 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).
+
+For example, the Engine Yard Cloud uses a header that looks like:
+
+![](https://img.skitch.com/20120915-mk8mnpdsu5nuym3bxs678qf1a8.png)
+
+The `app/views/user_impersonate/_header.html.haml` HAML partial for this header would be:
+
+``` haml
+%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.
+
+Configure alternate paths using:
+
+``` ruby
+???
+```
+
+### User model & lookup
+
+By default, it assumes the User model is `User`, that you use `User.find(id)` to find a user, and `aUser.id` to get the related id value.
+
+You can fix this default behavior in `config/initializers/user_impersonate.rb`, which is created by the generator above.
+
+``` ruby
+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?
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,41 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'UserImpersonate'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :cucumber => 'app:cucumber'
+# task :default => [:test, :spec, :cucumber]
+task :default => [:test, :cucumber]

data/app/assets/javascripts/user_impersonate/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/javascripts/user_impersonate/impersonate.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/stylesheets/user_impersonate/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/assets/stylesheets/user_impersonate/impersonate.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/app/controllers/user_impersonate/application_controller.rb

@@ -0,0 +1,4 @@
+module UserImpersonate
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/user_impersonate/impersonate_controller.rb

@@ -0,0 +1,107 @@
+require_dependency "user_impersonate/application_controller"
+
+module UserImpersonate
+  class ImpersonateController < ApplicationController
+    before_filter :authenticate_user!
+    before_filter :current_user_must_be_staff!, except: ["destroy"]
+    
+    # Display list of all users, except current (staff) user
+    # Is this exclusion unnecessary complexity?
+    # Normal apps wouldn't bother with this action; rather they would
+    # go straight to GET /impersonate/user/123 (create action)
+    def index
+      users_table = Arel::Table.new(user_table.to_sym) # e.g. :users
+      id_column = users_table[user_id_column.to_sym]   # e.g. users_table[:id]
+      @users = user_class.order("updated_at DESC").
+                    where(
+                      id_column.not_in [
+                        current_user.send(user_id_column.to_sym) # e.g. current_user.id
+                      ])
+      if params[:search]
+        @users = @users.where("name like ?", "%#{params[:search]}%")
+      end
+    end
+    
+    # Perform the user impersonate action
+    # GET /impersonate/user/123 
+    def create
+      @user = find_user(params[:user_id])
+      impersonate(@user)
+      redirect_on_impersonate(@user)
+    end
+    
+    # Revert the user impersonation
+    # GET /impersonation/revert
+    def destroy
+      unless current_staff_user
+        flash[:notice] = "You weren't impersonating anyone"
+        redirect_on_revert and return
+      end
+      user = current_user
+      revert_impersonate
+      if user
+        flash[:notice] = "No longer impersonating #{user}"
+        redirect_on_revert(user)
+      else
+        flash[:notice] = "No longer impersonating a user"
+        redirect_on_revert
+      end
+    end
+    
+    private
+    def current_user_must_be_staff!
+      unless user_is_staff?(current_user)
+        flash[:error] = "You don't have access to this section."
+        redirect_to :back
+      end
+    rescue ActionController::RedirectBackError
+      redirect_to '/'
+    end
+
+    # Helper to load a User, using all the UserImpersonate config options
+    def find_user(id)
+      user_class.send(user_finder_method, id)
+    end
+    
+    # Similar to user.staff?
+    # Using all the UserImpersonate config options
+    def user_is_staff?(user)
+      current_user.respond_to?(user_is_staff_method.to_sym) &&
+        current_user.send(user_is_staff_method.to_sym)
+    end
+
+    def user_finder_method
+      (UserImpersonate::Engine.config.try(:user_finder) || "find").to_sym
+    end
+
+    def user_class_name
+      UserImpersonate::Engine.config.try(:user_class) || "User"
+    end
+
+    def user_class
+      user_class_name.constantize
+    end
+    
+    def user_table
+      user_class_name.tableize
+    end
+    
+    def user_id_column
+      UserImpersonate::Engine.config.try(:user_id_column) || "id"
+    end
+    
+    def user_is_staff_method
+      UserImpersonate::Engine.config.try(:user_is_staff_method) || "staff?"
+    end
+    
+    def redirect_on_impersonate(impersonated_user)
+      url = UserImpersonate::Engine.config.try(:redirect_on_impersonate) || main_app.root_url
+      redirect_to url
+    end
+    
+    def redirect_on_revert(impersonated_user = nil)
+      url = UserImpersonate::Engine.config.redirect_on_revert || root_url
+      redirect_to url
+    end
+  end
+end

data/app/helpers/user_impersonate/application_helper.rb

@@ -0,0 +1,4 @@
+module UserImpersonate
+  module ApplicationHelper
+  end
+end

data/app/views/layouts/user_impersonate/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>User Impersonate</title>
+  <%= stylesheet_link_tag    "user_impersonate/application", :media => "all" %>
+  <%= javascript_include_tag "user_impersonate/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/user_impersonate/_header.html.erb

@@ -0,0 +1,60 @@
+<style>
+#impersonating {
+  width: 100%;
+  margin: 0;
+  padding: 12px 0;
+  background: #c70000;
+  border-bottom: 1px solid black;
+  line-height: 1.9;
+  font-size: 12px;
+  font-family: "Lucida Sans Unicode","Lucida Grande",Verdana,Arial,Helvetica,sans-serif;
+}
+#impersonating .impersonate-controls {
+  color: white;
+  font-weight: normal;
+  font-size: 15px;
+  max-width: 960px;
+  margin-left: auto;
+  margin-right: auto;
+}
+#impersonating .impersonate-controls .impersonate-info {
+  margin-bottom: 6px;
+  padding-bottom: 2px;
+  border-bottom: 1px solid #dd0000;
+}
+#impersonating .impersonate-controls form {
+  display: inline;
+  margin-right: 16px;
+}
+#impersonating .impersonate-controls .revert-form {
+  margin-left: 16px;
+}
+#impersonating .impersonate-controls select {
+  background: white;
+}
+#impersonating .impersonate-controls .admin_name, #impersonating .impersonate-controls .user_name, #impersonating .impersonate-controls .user_id, #impersonating .impersonate-controls .account_id {
+  font-weight: bold;
+}
+#impersonating .impersonate-controls a {
+  text-decoration: underline;
+  color: white;
+}
+</style>
+<div id="impersonating">
+  <div class="impersonate-controls">
+    <div class="impersonate-info">
+      You (
+      <span class="admin_name"><%= current_staff_user %></span>
+      ) are impersonating
+      <span class="admin_name"><%= current_user %></span>
+      ( User id: <%= current_user.to_param %> )
+    </div>
+
+    <div class="impersonate-buttons">
+      <%= form_tag impersonate_engine.revert_impersonate_user_url, 
+          :method => :delete, :class => 'revert-form' do %>
+        <button type = "submit"> Revert to admin</button>
+      <% end %>
+    </div>
+  </div>
+</div>