fairplaysk/datacamp

h1. "Restful Authentication Generator":http://github.com/Satish/restful-authentication

This widely-used plugin provides a foundation for securely managing user authentication:
* Login / logout
* Secure password handling
* Account activation by validating email
* Account approval / disabling by admin
* Rudimentary hooks for authorization and access control.

Several features were updated in May, 2008.
* "Stable newer version":http://github.com/technoweenie/restful-authentication/tree/master
* "'Classic' (backward-compatible) version":http://github.com/technoweenie/restful-authentication/tree/classic
* "Experimental version":http://github.com/technoweenie/restful-authentication/tree/modular (Much more modular, needs testing & review)

!! important: if you upgrade your site, existing user account !!
!! passwords will stop working unless you use @--old-passwords@ !!

h2. Issue Tracker

Please submit any bugs or annoyances at
* "http://github.com/Satish/restful-authentication/issues":http://github.com/Satish/restful-authentication/issues

h2. Documentation

This page has notes on
* "Installation":#INSTALL
* "New Features":#AWESOME
* "After installing":#POST-INSTALL

See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home (or the notes/ directory) if you want to learn more about:

* "Extensions, Addons and Alternatives":http://wiki.github.com/technoweenie/restful-authentication/addons such as HAML templates
* "Security Design Patterns":http://wiki.github.com/technoweenie/restful-authentication/security-patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
* "Authentication":http://wiki.github.com/technoweenie/restful-authentication/authentication -- Lets a visitor identify herself (and lay  claim to her corresponding Roles and measure of Trust)
* "Trust Metrics":http://wiki.github.com/technoweenie/restful-authentication/trustification -- Confidence we can rely on the outcomes of this visitor's actions.
* "Authorization":http://wiki.github.com/technoweenie/restful-authentication/authorization and Policy -- Based on trust and identity, what actions may this visitor perform?
* "Access Control":http://wiki.github.com/technoweenie/restful-authentication/access-control -- How the Authorization policy is actually enforced in your code (A: hopefully without turning it into  a spaghetti of if thens)
* "Rails Plugins":http://wiki.github.com/technoweenie/restful-authentication/rails-plugins for Authentication, Trust,  Authorization and Access Control
* "Tradeoffs":http://wiki.github.com/technoweenie/restful-authentication/tradeoffs -- for the paranoid or the curious, a rundown of tradeoffs made in the code
* "CHANGELOG":http://wiki.github.com/technoweenie/restful-authentication/CHANGELOG -- Summary of changes to internals
* "TODO":http://wiki.github.com/technoweenie/restful-authentication/todo -- Ideas for how you can help


These best version of the release notes are in the notes/ directory in the "source code":http://github.com/technoweenie/restful-authentication/tree/master -- look there for the latest version. The wiki versions are taken (manually) from there.

h2(#AWESOME). Exciting new features

h3. Stories

There are now "Cucumber":http://wiki.github.com/aslakhellesoy/cucumber/home features that allow expressive, enjoyable tests for the authentication code. The flexible code for resource testing in stories was extended from "Ben Mabey's.":http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/

h3. Modularize to match security design patterns:

* Authentication (currently: password, browser cookie token, HTTP basic)
* Trust metric (email validation)
* Authorization (stateful roles)
* Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins

h3. Other

* Added a few helper methods for linking to user pages
* Uniform handling of logout, remember_token
* Stricter email, login field validation
* Minor security fixes -- see CHANGELOG


h2. Non-backwards compatible Changes

Here are a few changes in the May 2008 release that increase "Defense in Depth"
but may require changes to existing accounts

* If you have an existing site, none of these changes are compelling enough to warrant migrating your userbase.
* If you are generating for a new site, all of these changes are low-impact. You should apply them.

h3. Passwords

The new password encryption (using a site key salt and stretching) will break existing user accounts' passwords.  We recommend you use the @--old-passwords@
option or write a migration tool and submit it as a patch.  See the "Tradeoffs":http://wiki.github.com/technoweenie/restful-authentication/tradeoffs note for more information.

h3. Validations

By default, email and usernames are validated against a somewhat strict pattern; your users' values may be now illegal.  Adjust to suit.


h2(#INSTALL). Installation

This is a basic restful authentication generator for rails, taken from acts as authenticated.  Currently it requires Rails3 beta.

**IMPORTANT FOR RAILS > 2.1 USERS** To avoid a @NameError@ exception ("lighthouse tracker ticket":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/tickets/2-not-a-valid-constant-name-errors#ticket-2-2), check out the code to have an _underscore_ and not _dash_ in its name:

If you're using git as your source control, you have three options.

* Install as a plugin <pre><code>rails plugin install git://github.com/Satish/restful-authentication.git restful_authentication</code></pre>

* Checkout into @vendor/plugins@ using
<pre><code>git clone git://github.com/Satish/restful-authentication.git restful_authentication</code></pre>and delete the .git folder inside the directory. (This will break the connection with the github repository, and allow you to include the code into your project with git add)

* Use git submodule. From the top level of your project, add the plugin
<pre><code>git submodule add git://github.com/Satish/restful-authentication.git vendor/plugins/restful_authentication</code></pre>This will create a reference link to the repository, which can be save into your project. You will need to let capistrano know that you want to update submodules on deploy via @set :git_enable_submodules, 1@.

"git-submodule docs":http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html

To use the generator:
<pre><code>
  rails g authenticated user sessions \
    --include-activation \
    --stateful \
    --rspec \
    --skip-migration \
    --skip-routes \
    --old-passwords
</code></pre>

* The first parameter specifies the model that gets created in signup (typically a user or account model).  A model with migration is created, as well as a basic controller with the create method. You probably want to say "User" here.

* The second parameter specifies the session controller name(options default to @sessionsController@).  This is the controller that handles the actual login/logout function on the site. (probably: "Session").

* @--include-activation@: Generates the code for a ActionMailer and its respective Activation Code through email.

* @--stateful@: Builds in support for acts_as_state_machine and generates activation code.  (@--stateful@ implies @--include-activation@). Based on the idea at "http://www.vaporbase.com/postings/stateful_authentication":http://www.vaporbase.com/postings/stateful_authentication. Passing @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip resource generation both useful if you've already run this generator. (Needs the "acts_as_state_machine plugin":http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/, but new installs should probably run with @--aasm@ instead.)

* @--aasm@: Works the same as stateful but uses the "updated aasm gem":http://github.com/rubyist/aasm/tree/master<br /> Add <code>gem 'rubyist-aasm', :require => 'aasm'</code> to @Gemfile@ for use in projects that use rails3-beta

* @--rspec@: Generate RSpec tests and Stories in place of standard rails tests. This requires the "RSpec-2 for Rails-3":http://github.com/rspec/rspec-rails, run @gem install rspec-rails --pre@ to install RSpec-2 for Rails-3(make sure you @rails g rspec:install@ after installing RSpec.) The rspec and story suite are much more thorough than the rails tests, and changes are unlikely to be backported.

* @--old-passwords@: Use the older password scheme (see [[#COMPATIBILITY]], above)

* @--skip-migration@: Don't generate a migration file for this model

* @--skip-routes@: Don't generate a resource line in @config/routes.rb@


h2(#POST-INSTALL). After installing

The below assumes a Model named 'User' and a Controller named 'Session'; please alter to suit. There are additional security minutae in @notes/README-Tradeoffs@ -- only the paranoid or the curious need bother, though.

* Add these familiar login URLs to your @config/routes.rb@ if you like:
<pre><code>
 match 'login' => 'sessions#new', :as => :login
 match 'logout' => 'sessions#destroy', :as => :logout
 match 'signup' => 'users#new', :as => :signup
</code></pre>

* With @--include-activation@, also add to your @config/routes.rb@:
<pre><code>match 'activate/:activation_code' => 'users#activate', :as => :activate, :activation_code => nil</code></pre>
and add an observer to @config/application.rb@:
<pre><code>config.active_record.observers = :user_observer</code></pre>
Pay attention, may be this is not an issue for everybody, but if you should have problems, that the sent activation_code does match with that in the database stored, reload your user object before sending its data through email something like:
<pre><code>
class UserObserver < ActiveRecord::Observer
  def after_create(user)
    user.reload
    UserMailer.deliver_signup_notification(user)
  end
  def after_save(user)
    user.reload
    UserMailer.deliver_activation(user) if user.recently_activated?
  end
end
</code></pre>


* With @--stateful@, add an observer to config/environment.rb:
<pre><code>config.active_record.observers = :user_observer</code></pre>
and modify the users resource line in @config/routes.rb@ to read
<pre><code>
resources :users do
  member do
    put :suspend
    put :unsuspend
    delete :purge
  end
end
</code></pre>

* If you use a public repository for your code (such as github, rubyforge, gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like '/config/initializers/site_keys.rb' to your .gitignore or do the svn ignore dance), but make sure you DO keep it backed up somewhere safe.