ruby script/plugin install http://svn.codahale.com/simple_http_auth

Overview
==========

1. Install the plugin. (See previous section)
2. Add authentication requirements to your controllers as you see fit.
3. Ride a bike instead of driving your car.

Specifics
============

simple_http_auth has one method: +requires_authentication+. To wit:

  class PuppyHeavenController < ApplicationController
    requires_authentication :using => lambda{ |username, password| username != 'cat' }
    # ... actions go here ...
  end

+requires_authentication+ takes a hash of options as its lone argument, only one of which is mandatory: :using. :using is the event handler for any authorization attempt, and is passed two arguments: the username and password provided by the user during their login attempt. :using can be a Proc, as in the example above, or a String or Symbol referencing one of the controller's methods. For example:

  class PuppyHeavenController < ApplicationController
    requires_authentication :using => :authenticate
    # ... actions go here ...
    
  private
    def authenticate(username, password)
      return username == 'dog' && password == 'woof'
    end
  end

The event handler for :using should return a Boolean value: true if the user is authorized to access the action, false if not. simple_http_auth doesn't maintain your user database, make you use a specific model or controller, or anything. You're responsible for all that.

By default, +requires_authentication+ protects all of the controller's actions, but this behavior is modifiable by using the :except and :only options:

  class PuppyHeavenController < ApplicationController
    requires_authentication :using => lambda{ |username, password| username != 'cat' },
                            :except => [:publicly_accessible_action]
    # ... actions go here ...
  end

or

  class PuppyHeavenController < ApplicationController
    requires_authentication :using => lambda{ |username, password| username != 'cat' },
                            :only => [:totally_secret]
    # ... actions go here ...
  end

Other options include:

:realm -- the authentication "realm," which is usually displayed in the browser's login dialog. Defaults to "Login Required".

:error_msg -- the message displayed on an unsuccessful access attempt. Defaults to "401 Unauthorized: You are not authorized to view this page."

Logging Out
=============

Occasionally someone may want to exit your wonderful application, but I wouldn't know why. To enable these backsliders (or users in internet cafes, at work, on their sister's computer, whatever), simple_http_auth provides for logging out:

  class HappyMagicController < ApplicationController
    requires_authentication :using => :whatever,
                            :logout_on => :logout
    
    def logout
      # logout.rhtml will be displayed after the user logs out
    end
  end

Using HTTP Authentication On Hosting Services
======================================

If you're like most people, you've got a little corner on a shared host somewhere, and your Rails apps get managed by someone else. If that's the case, you make need to jump through a few hoops to get HTTP authentication working. Some virtual hosting configurations of Apache, for example, don't pass HTTP authentication headers to FastCGI applications like Rails, so you'll need to add the following line to your public/.htaccess file if HTTP authentication doesn't appear to work:

  RewriteRule ^(.*)$ dispatch.fcgi [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization},QSA,L]

(This is guaranteed to work on Dreamhost, but I'm not sure about others. Email me with details if you get it working in other environments and need to change this.)

There is another option which influences how simple_http_auth gets the user's login and password:

:at -- an array of header fields where the user's login and password can be found. Defaults to ['REDIRECT_REDIRECT_X_HTTP_AUTHORIZATION', 'REDIRECT_X_HTTP_AUTHORIZATION', 'X-HTTP_AUTHORIZATION', 'HTTP_AUTHORIZATION'], which should cover just about everything. These are tried in order, from first to last, and the first header which exists is used as the authentication data. If you're getting a login dialog, but nothing seems to let you log in (and you're *damn* sure your :using handler is working), try fiddling with this to make sure it's actually receiving the data. For example:

  class PuppyHeavenController < ApplicationController
    requires_authentication :using => lambda{ |username, password| username != 'cat' },
                            :at => ['WOW-WHAT-A-STRANGE-HTTP-SERVER-YOU-HAVE']
    # ... actions go here ...
  end

There is currently no advanced documentation for this plugin.