"For over a thousand generations the Jedi Knights were the guardians of peace and justice in the Old Republic. Before the dark times, before the Empire." -- Obi-Wan Kenoby

= Cerberus

Cerberus is a Rack middleware for form-based authentication. Its purpose is only 
to offer a nicer (or more actual) replacement for Basic HTTP authentication.

Install with:

	# sudo gem install rack-cerberus

You can use it almost the same way you use <tt>Rack::Auth::Basic</tt>:

	require 'cerberus'
	use Rack::Session::Cookie
	use Cerberus do |login, pass|
		pass=='secret'
	end
	
Like in that example, make sure you have a session, because Cerberus use it for
persistent login.
	
There is an optional hash you can add for personalizing it. Options are:

* <tt>:company_name</tt>
* <tt>:fg_color</tt> (foreground color)
* <tt>:bg_color</tt> (background color)
* <tt>:icon_url</tt> (for a company logo or any icon)

Which is used that way:

	use Cerberus, {:company_name => 'Nintendo'} do |login, pass|
		pass=='secret'
	end
	
Just like <tt>Rack::Auth::Basic</tt>, Cerberus yields login and pass, and delegate authentication
to the block you send it which should return a boolean.

If you want to see a concrete example, go into the Cerberus directory and run:

	# rackup example.ru
	
It's gonna start the example at http://localhost:9292

=== Logout

Any request to <tt>/logout</tt> on the path where the middleware is mounted will log you out.
In other words, if you put the middleware at <tt>/admin</tt>, query <tt>/admin/logout</tt> to be
logged out. Pretty simple.

=== Help

If you want to help me, don't hesitate to fork that project on Github or send patches.

=== Changelog

	0.0.1 Changed Everything somehow
	0.1.0 Make it possible to authenticate through GET request (for restful APIs)
	0.1.1 Documentation improvement
	0.1.2 Raise message when using without session

=== Copyright

(c) 2010 Mickael Riga - see MIT_LICENCE for details