Gatekeeper

Gatekeeper can connect any Rack-compatible application to a Hot Ink SSO server. It allows you to easily verify the identity of a user against Hot Ink’s user information database. It makes some basic information about the user available to your application.

Gatekeeper is largely a rewrite of Hancock-Client (github.com/atmos/hancock-client). The functionality is different but the spirit is the same.

Installation

This is the easy part.

gem install gatekeeper --source http://gemcutter.org

Using Gatekeeper

Gatekeeper is implemented in Sinatra, but it can authenticate any Rack-based application. That could be Rails, Sinatra, Rack whatever. You’ll be surprised how easy it is.

Simply add the following into your Rack stack, by simply placing it directly into your Sinatra app as middleware, or if you’re building a Rack app, add it to your stack in config.ru:

use Rack::Session::Cookie
use Gatekeeper::Middleware do |sso|
  sso.sso_url = "http://your_sso_server.net/sso"
end

Be sure to use the session middleware when building a Rack app, or to enable :sessions when using Sinatra. Gatekeeper relies on sessions to store authentication information. Also be sure to include the correct SSO server URL.

With Rails

When using Gatekeeper with Rails, you should create a ‘metal’ Sinatra app to keep it in, then implement it as show above. It’s pretty easy, just run script/generate metal sso. Inside, you should have:

require(File.dirname(__FILE__) + "/../../config/environment") unless defined?(Rails)
require 'sinatra/base'
require 'logger'

class Sso < Sinatra::Base
  use Gatekeeper::Middleware do |sso|
    sso.sso_url = "http://your_sso_server.net/sso"
  end
end

When using Rails, you should be sure not to enable sessions in your Sinatra metal. Rails takes care of the session. If you re-enable, you’ll overwrite what Rails has already found and your authentication will not work

In your app

Gatekeeper puts the received user details in a hash accessible using session. Things are a little more convenient using the helpers. To do that, simply include Gatekeeper::Helpers::Authentication in your app. You can then use the following methods:

current_user

Will return nil or the current user’s id, depending on whether or not the user is logged in.
is_admin?

Is this user a Hot Ink admin? You may have some tasks that only admin users can do.
is_manager_of?(hotink_account_id)

Will return true if the user is a manager of the account who’s id you passed in.

Your app can use a simple require_user method as a before filter to ensure that users are logged in, the most basic of which could look like this:

def require_user
 unless current_user
   redirect_to "/sso/login?return_to=#{request.request_uri}"
   false # if you're using this as a Rails before filter, return false 
 end
end

Note on Patches/Pull Requests