Skip to content

Commit

Permalink
README and gemspec updated.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Satish
Satish committed Apr 22, 2010
1 parent cc78f7e commit 3824896
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 166 deletions.
222 changes: 87 additions & 135 deletions README.textile
View file
@@ -1,7 +1,6 @@
h1. "Restful Authentication Generator":http://github.com/technoweenie/restful-authentication
h1. "Restful Authentication Generator":http://github.com/Satish/restful-authentication

This widely-used plugin provides a foundation for securely managing user
authentication:
This widely-used plugin provides a foundation for securely managing user authentication:
* Login / logout
* Secure password handling
* Account activation by validating email
Expand All @@ -13,21 +12,13 @@ Several features were updated in May, 2008.
* "'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 !!

***************************************************************************
!! 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 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).

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

h2. Documentation

Expand All @@ -36,35 +27,27 @@ This page has notes on
* "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:
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
* "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.

***************************************************************************
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>
h2. Exciting new features
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/
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:

Expand All @@ -80,145 +63,114 @@ h3. Other
* 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.
* 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]] note for more information.
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.

***************************************************************************

<a id="INSTALL"/> </a>
h2. Installation
h2(#INSTALL). Installation

This is a basic restful authentication generator for rails, taken from
acts as authenticated. Currently it requires Rails 1.2.6 or above.
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:
* 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:
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>

./script/generate authenticated user sessions \
* 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 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").
* 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.
* @--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.)
* @--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
* @--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 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.
* @--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)
* @--old-passwords@: Use the older password scheme (see [[#COMPATIBILITY]], above)

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

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

***************************************************************************
<a id="POST-INSTALL"/> </a>
h2. 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.
h2(#POST-INSTALL). After installing

* Add these familiar login URLs to your @config/routes.rb@ if you like:
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.

<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>
* 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>
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>
<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 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.
<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.

0 comments on commit 3824896

Please sign in to comment.