hancock

It's like your John Hancock for all of your company's apps.

A lot of this is extracted from our internal single sign on server at Engine Yard. We use a different datamapper backend but it should be a great start for most people.

Features

An OpenID based Single Sign On server that provides:

  • a single authoritative source for user authentication
  • a whitelist for consumer applications
  • integration with the big ruby frameworks via rack.
  • configurable sreg parameters to consumers

How it Works

SSO Handshake

This handshake seems kind of complex but it only happens when you need to validate a user session on the consumer.

Your Rackup File

#  thin start -p PORT -R config.ru
require 'rubygems'
require 'hancock'

DataMapper.setup(:default, "sqlite3:///#{Dir.pwd}/development.db")

Sinatra::Mailer.config = {
  :host   => 'smtp.example.com',
  :port   => '25',
  :user   => 'sso',
  :pass   => 'lolerskates',
  :auth   => :plain # :plain, :login, :cram_md5, the default is no auth
  :domain => "example.com" # the HELO domain provided by the client to the server
}

class Dragon < Hancock::App
  set :views,  'views'
  set :public, 'public'
  set :environment, :production

  set :provider_name, 'Example SSO Provider'
  set :do_not_reply,  '[email protected]'

  get '/' do
    redirect '/sso/login' unless session[:hancock_server_user_id]
    erb "<h2>Hello <%= session[:first_name] %><!-- <%= session.inspect %>"
  end
end
run Dragon

Installation

% gem sources
*** CURRENT SOURCES ***

http://gems.rubyforge.org/
http://gems.engineyard.com
http://gems.github.com

You need a few gems to function

% sudo gem install dm-core do_sqlite3
% sudo gem install sinatra ruby-openid

You need a few extra gems to run the specs % sudo gem install rspec webrat rack-test cucumber

Deployment Setup

You can deploy hancock on any rack compatible setup. You need a database that datamapper can connect to. Generate an example rackup file for yourself based on the example above.

% irb
>> require 'rubygems'
=> false
>> require 'hancock'
=> true
>> DataMapper.setup(:default, "sqlite3:///#{Dir.pwd}/development.db")
=> #<DataMapper::Adapters::Sqlite3Adapter:0x1ae639c ...>
>> DataMapper.auto_migrate!
=> [Hancock::User, Hancock::Consumer]

Consult the datamapper documentation if you need to connect to something other than sqlite. This runs the initial user migration to bootstrap your db.

>> Hancock::Consumer.create(:url => 'http://hr.example.com/sso/login', :label => 'Human Resources', :internal => true)
=> ...
>> Hancock::Consumer.create(:url => 'http://localhost:3000/sso/login', :label => 'Local Rails Dev', :internal => false)
=> ...
>> Hancock::Consumer.create(:url => 'http://localhost:4000/sso/login', :label => 'Local Merb Dev', :internal => false)
=> ...
>> Hancock::Consumer.create(:url => 'http://localhost:4567/sso/login', :label => 'Local Sinatra Dev', :internal => false)

Here's how you setup most frameworks as consumers. In a production environment you'd lock this down

Feedback

Sponsored By