SinatraImpersonator

Installation

Add these lines to your application's Gemfile:

source 'https://gem.fury.io/universityofyork/' do
  gem 'uoy-faculty-sinatra-impersonate', '~> 0.1', require: 'sinatra/impersonate'
end

And then execute:

$ bundle

Or install it yourself as:

$ gem install uoy-faculty-sinatra-impersonate

Usage

This wraps up an RBAC::User object and allows the user to impersonate another user, while retaining information on who is actually logged in.

Requirements

This extension requires sessions to be enabled.

Setup

This extension handles permissions in two parts:

• An rbac permission that allows users to impersonate (any user without this permission will be denied access)
• A list of usernames that can be impersonated.

The list of usernames should be generated per-app, and probably per-user.

To set the impersonate permission, add the following to your configure block in your app.rb:

configure do
  ...
  
  Sinatra::Impersonate.configure do |config|
    config.permission = :permission_given_to_those_that_can_impersonate
  end

  ...
end

To set up the logged in user as a possible impersonator; add the following to your before block in app.rb:

before do
  ...

    @rbac = RBAC::Controller.new(DB)
    @logged_in_user = Sinatra::Impersonate::Impersonator.new @rbac, session
    @logged_in_user.valid_targets impersonator_user_list(@logged_in_user.actual_user)

  ...
end

Here, the impersonator_user_list function is defined within the app - it takes the current user and returns a list of usernames that can be impersonated.

Routes

The extension defines two routes to allow a user to manage who they are impersonating:

• POST /impersonate
  • Expects the username parameter to be set to the desired user to be impersonated
  • Will call impersonate on the currently logged in user to try to set up impersonation
• GET /impersonate/stop
  • Will stop the current user from impersonating

UI

See samples/navbar.erb for an example UI element that can be added to the navbar to allow a user to enter a username for impersonation.

Further examples - for example, picking a user from a list - will be added in due course.

Development

Versioning

Your Gem's version is picked up automatically from lib/sinatra/impersonate.rb. When any changes are pushed to master, after the normal CI tasks the pipeline will push to gemfury automatically. The usual workflow is:

• For minor changes, update VERSION and make the change in a single commit

• For anything else, create a branch and set VERSION to the version you're aiming to release for. Make the changes; when the branch is merged, the gem will be uploaded.

Note that gemfury will never overwrite an existing gem version, even if the old one is yanked!

Running tests

Tests can be run via rake: bundle exec rake spec - this doesn't run performance tests; they can be run separately via bundle exec rake perf.

You can also run rspec normally e.g. bundle exec rspec -fd.

Identifying Performance Tests

If you have performance tests that take a while, tag the context / describe block like this:

context 'when foo is bar baz', :perf do
  ...
end

Contributing

Bug reports and pull requests are welcome at https://bitbucket.org/university-of-york/faculty-new-gem