This repository has been archived by the owner on Jul 21, 2020. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
c568428
commit 52d71a8
Showing
1 changed file
with
227 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,227 @@ | ||
| # "Restful Authentication Generator":http://github.com/technoweenie/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 | ||
| *************************************************************************** | ||
|
|
||
| ## Issue Tracker | ||
|
|
||
| Please submit any bugs or annoyances on the lighthouse tracker at | ||
| * "http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview | ||
|
|
||
| For anything simple enough, please github message both maintainers: Rick Olson | ||
| ("technoweenie":http://github.com/technoweenie) and Flip Kromer | ||
| ("mrflip":http://github.com/mrflip). | ||
|
|
||
| *************************************************************************** | ||
|
|
||
| ## 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":addons such as HAML templates | ||
| * "Security Design Patterns":security-patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png | ||
| * Authentication -- Lets a visitor identify herself (and lay claim to her corresponding Roles and measure of Trust) | ||
| * "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions. | ||
| * Authorization and Policy -- Based on trust and identity, what actions may this visitor perform? | ||
| * 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 for Authentication, Trust, Authorization and Access Control | ||
| * Tradeoffs -- for the paranoid or the curious, a rundown of tradeoffs made in the code | ||
| * CHANGELOG -- Summary of changes to internals | ||
| * 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. | ||
|
|
||
| *************************************************************************** | ||
|
|
||
| <a id="AWESOME"/> </a> | ||
|
|
||
| ## Exciting new features | ||
|
|
||
| ### 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/ | ||
|
|
||
| ### 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 | ||
|
|
||
| ### 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 | ||
|
|
||
| *************************************************************************** | ||
|
|
||
| ## 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. | ||
|
|
||
| ### 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]] note for more information. | ||
|
|
||
| ### Validations | ||
|
|
||
| By default, email and usernames are validated against a somewhat strict pattern; your users' values may be now illegal. Adjust to suit. | ||
|
|
||
| *************************************************************************** | ||
|
|
||
| <a id="INSTALLATION"/> </a> | ||
|
|
||
| ## Installation | ||
|
|
||
| This is a basic restful authentication generator for rails, taken from | ||
| acts as authenticated. Currently it requires Rails 1.2.6 or above. | ||
|
|
||
| **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: | ||
| * either use <code>git clone git://github.com/technoweenie/restful-authentication.git restful_authentication</code> | ||
| * or rename the plugin's directory to be <code>restful_authentication</code> after fetching it. | ||
|
|
||
| To use the generator: | ||
|
|
||
| ./script/generate authenticated user sessions \ | ||
| --include-activation \ | ||
| --stateful \ | ||
| --rspec \ | ||
| --skip-migration \ | ||
| --skip-routes \ | ||
| --old-passwords | ||
|
|
||
| * 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. 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]]. 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 | ||
|
|
||
| * --rspec: Generate RSpec tests and Stories in place of standard rails tests. | ||
| This requires the | ||
| "RSpec and Rspec-on-rails plugins":http://rspec.info/ | ||
| (make sure you "./script/generate rspec" 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@ | ||
|
|
||
| *************************************************************************** | ||
| <a id="POST-INSTALL"/> </a> | ||
|
|
||
| ## 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> | ||
| map.signup '/signup', :controller => 'users', :action => 'new' | ||
| map.login '/login', :controller => 'session', :action => 'new' | ||
| map.logout '/logout', :controller => 'session', :action => 'destroy' | ||
| </code></pre> | ||
|
|
||
| * With @--include-activation@, also add to your @config/routes.rb@: | ||
|
|
||
| <pre><code> | ||
| map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil | ||
| </code></pre> | ||
|
|
||
| and add an observer to @config/environment.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 to read | ||
|
|
||
| map.resources :users, :member => { :suspend => :put, | ||
| :unsuspend => :put, | ||
| :purge => :delete } | ||
|
|
||
| * 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. |