merb-auth

h1. MerbAuth - Merb Merb::Authentication

h2. An extensible architecture for authentication

• Speaks fluent HTTP, even the errors
• Pluggable Architecture (so that you can use any authentication algorithms you like)
• Cascading Merb::Authentication (if one method fails, another is attempted, then another. When no methods succeed, authentication fails)

h2. Principles

Sessions are authenticated

Just because one method of authentication fails doesn't mean the session, can't be authenticated another way. This is especially true if your application has an external API as well as a public interface.

HTTP has built-in "Errors":http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html which every web-browser (should) know how to speak. If you're application speaks in HTTP Verbs (GET, POST, PUT, DELETE), it should also serve the correct HTTP Errors when things go wrong.

h2. What is it

The merb-auth gem is the default implementation of merb-auth-core and merb-auth-more for the default Merb Stack. Included are:

merb-auth-slice-password # A basic slice that provides login and logout functionality

Strategies: :default_password_form # Form based login via a "login" field and "password" field :default_basic_auth # Basic authentication

Mixins: redirect_back # For redirect_back_or functionality salted_user # Automtaically provides the required methods on your user model

h3. Get merb-auth

merb-auth is bundled with the merb gem. To get it as stand alone you can get it two ways.

Gem Style @sudo gem install merb-auth@

From Source

git clone http://github.com/wycats/merb.git
cd merb/merb-auth
sudo rake install

h2. Basic Setup

h3. Application Setup (Stack)

When you generate your application with @merb-gen app my_app@ your almost ready to go.

You'll need something to protect @merb-gen resource foos@

You'll need to make your database: @rake db:automigrate@

Also you need a user

  $ merb -i
  >> u = User.new(:login => "homer")
  >> u.password = u.password_confirmation = "sekrit"
  >> u.save

No you should setup authentication for the things you want to protect:

  # config/router.rb
  authenticate do
    resources :foos
  end

You can protect your controller at an action level also

  # app/controllers/foos.rb 
  before :ensure_authenticated

Fire It Up!

@merb@

h3. Customize your setup

In the Merb.root/merb/merb-auth directory there are a couple of files that are generated for you by the stack generator. These are @setup.rb@ and @strategies.rb@

By default these setup merb-auth to work with the default stack. To customize it, modify these two files to get the results you want. Serialize in and out of the session, change the user model for use with the default strategies.

You can of course not use the default strategies and declare your own, or mix and match them.

Configure your routes in the config/router.rb file.