dcrec1 / restful-authentication-i18n forked from technoweenie/restful-authentication

Generates common user authentication code for Rails with support for i18n, a full rspec suite and optional Acts as State Machine support built-in

This URL has Read+Write access

restful-authentication-i18n / README.textile
raw normal view history
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 1 h1. "Restful Authentication Generator":http://github.com/technoweenie/restful-authentication
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 2
3 This widely-used plugin provides a foundation for securely managing user
4 authentication:
5 * Login / logout
6 * Secure password handling
7 * Account activation by validating email
8 * Account approval / disabling by admin
9 * Rudimentary hooks for authorization and access control.
10
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 11 Several features were updated in May, 2008.
12 * "Stable newer version":http://github.com/technoweenie/restful-authentication/tree/master
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 13 * "'Classic' (backward-compatible) version":http://github.com/technoweenie/restful-authentication/tree/classic
14 * "Experimental version":http://github.com/technoweenie/restful-authentication/tree/modular (Much more modular, needs testing & review)
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 15
16 !! important: if you upgrade your site, existing user account !!
17 !! passwords will stop working unless you use --old-passwords !!
18
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 19 ***************************************************************************
20
21 h2. Issue Tracker
22
23 Please submit any bugs or annoyances on the lighthouse tracker at
24 * "http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview":http://rails_security.lighthouseapp.com/projects/15332-restful_authentication/overview
25
2dc76e7c » Philip (flip) Kromer 2008-08-26 Added me as maintenance monkey 26 For anything simple enough, please github message both maintainers: Rick Olson
27 ("technoweenie":http://github.com/technoweenie) and Flip Kromer
28 ("mrflip":http://github.com/mrflip).
29
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 30 ***************************************************************************
31
32 h2. Documentation
33
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 34 This page has notes on
35 * "Installation":#INSTALL
36 * "New Features":#AWESOME
37 * "After installing":#POST-INSTALL
38
39 See the "wiki":http://github.com/technoweenie/restful-authentication/wikis/home
40 (or the notes/ directory) if you want to learn more about:
41
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 42 * "Extensions, Addons and Alternatives":addons such as HAML templates
43 * "Security Design Patterns":security-patterns with "snazzy diagram":http://github.com/technoweenie/restful-authentication/tree/master/notes/SecurityFramework.png
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 44 * [[Authentication]] -- Lets a visitor identify herself (and lay claim to her corresponding Roles and measure of Trust)
45 * "Trust Metrics":Trustification -- Confidence we can rely on the outcomes of this visitor's actions.
46 * [[Authorization]] and Policy -- Based on trust and identity, what actions may this visitor perform?
47 * [[Access Control]] -- How the Authorization policy is actually enforced in your code (A: hopefully without turning it into a spaghetti of if thens)
48 * [[Rails Plugins]] for Authentication, Trust, Authorization and Access Control
49 * [[Tradeoffs]] -- for the paranoid or the curious, a rundown of tradeoffs made in the code
50 * [[CHANGELOG]] -- Summary of changes to internals
51 * [[TODO]] -- Ideas for how you can help
52
53 These best version of the release notes are in the notes/ directory in the
54 "source code":http://github.com/technoweenie/restful-authentication/tree/master
55 -- look there for the latest version. The wiki versions are taken (manually)
56 from there.
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 57
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 58 ***************************************************************************
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 59
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 60 <a id="AWESOME"/> </a>
61 h2. Exciting new features
62
63 h3. Stories
64
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 65 There are now "Cucumber":http://wiki.github.com/aslakhellesoy/cucumber/home features that allow expressive, enjoyable tests for the
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 66 authentication code. The flexible code for resource testing in stories was
67 extended from "Ben Mabey's.":http://www.benmabey.com/2008/02/04/rspec-plain-text-stories-webrat-chunky-bacon/
68
69 h3. Modularize to match security design patterns:
875781d5 » Philip (flip) Kromer 2008-05-20 Fixed the 'made some method... 70
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 71 * Authentication (currently: password, browser cookie token, HTTP basic)
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 72 * Trust metric (email validation)
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 73 * Authorization (stateful roles)
c394d99e » Philip (flip) Kromer 2008-05-18 Organized notes 74 * Leave a flexible framework that will play nicely with other access control / policy definition / trust metric plugins
75
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 76 h3. Other
875781d5 » Philip (flip) Kromer 2008-05-20 Fixed the 'made some method... 77
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 78 * Added a few helper methods for linking to user pages
79 * Uniform handling of logout, remember_token
80 * Stricter email, login field validation
81 * Minor security fixes -- see CHANGELOG
c394d99e » Philip (flip) Kromer 2008-05-18 Organized notes 82
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 83 ***************************************************************************
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 84
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 85 h2. Non-backwards compatible Changes
c394d99e » Philip (flip) Kromer 2008-05-18 Organized notes 86
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 87 Here are a few changes in the May 2008 release that increase "Defense in Depth"
88 but may require changes to existing accounts
c394d99e » Philip (flip) Kromer 2008-05-18 Organized notes 89
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 90 * If you have an existing site, none of these changes are compelling enough to
91 warrant migrating your userbase.
92 * If you are generating for a new site, all of these changes are low-impact.
93 You should apply them.
94
95 h3. Passwords
96
97 The new password encryption (using a site key salt and stretching) will break
98 existing user accounts' passwords. We recommend you use the --old-passwords
99 option or write a migration tool and submit it as a patch. See the
100 [[Tradeoffs]] note for more information.
101
102 h3. Validations
103
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 104 By default, email and usernames are validated against a somewhat strict pattern; your users' values may be now illegal. Adjust to suit.
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 105
106 ***************************************************************************
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 107
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 108 <a id="INSTALL"/> </a>
109 h2. Installation
2366199c » technoweenie 2006-08-01 initial commit of the restf... 110
8a761fe0 » Philip (flip) Kromer 2008-05-16 Documented all the flags, a... 111 This is a basic restful authentication generator for rails, taken from
1c01c02b » dcrec1 2008-10-12 updated README and fixed in... 112 acts as authenticated. Currently it requires Rails 2.2 or above.
2366199c » technoweenie 2006-08-01 initial commit of the restf... 113
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 114 **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:
115 * either use <code>git clone git://github.com/technoweenie/restful-authentication.git restful_authentication</code>
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 116 * or rename the plugin's directory to be <code>restful_authentication</code> after fetching it.
117
118 To use the generator:
2366199c » technoweenie 2006-08-01 initial commit of the restf... 119
3e10a0ba » technoweenie 2007-11-20 dont reset_session by defau... 120 ./script/generate authenticated user sessions \
8a761fe0 » Philip (flip) Kromer 2008-05-16 Documented all the flags, a... 121 --include-activation \
122 --stateful \
62216789 » Philip (flip) Kromer 2008-05-17 Added a --skip-routes flag ... 123 --rspec \
124 --skip-migration \
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 125 --skip-routes \
126 --old-passwords
2366199c » technoweenie 2006-08-01 initial commit of the restf... 127
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 128 * The first parameter specifies the model that gets created in signup (typically
129 a user or account model). A model with migration is created, as well as a
130 basic controller with the create method. You probably want to say "User" here.
2366199c » technoweenie 2006-08-01 initial commit of the restf... 131
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 132 * The second parameter specifies the session controller name. This is the
133 controller that handles the actual login/logout function on the site.
134 (probably: "Session").
2366199c » technoweenie 2006-08-01 initial commit of the restf... 135
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 136 * --include-activation: Generates the code for a ActionMailer and its respective
137 Activation Code through email.
e1e49b11 » technoweenie 2006-12-18 typos, remove authenticated... 138
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 139 * --stateful: Builds in support for acts_as_state_machine and generates
140 activation code. (@--stateful@ implies @--include-activation@). Based on the
141 idea at [[http://www.vaporbase.com/postings/stateful_authentication]]. Passing
142 @--skip-migration@ will skip the user migration, and @--skip-routes@ will skip
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 143 resource generation -- both useful if you've already run this generator.
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 144 (Needs the "acts_as_state_machine plugin":http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/,
145 but new installs should probably run with @--aasm@ instead.)
2d24dae0 » codafoo 2008-06-03 Add in support for AASM 146
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 147 * --aasm: Works the same as stateful but uses the "updated aasm gem":http://github.com/rubyist/aasm/tree/master
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 148
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 149 * --rspec: Generate RSpec tests and Stories in place of standard rails tests.
150 This requires the
151 "RSpec and Rspec-on-rails plugins":http://rspec.info/
152 (make sure you "./script/generate rspec" after installing RSpec.) The rspec
153 and story suite are much more thorough than the rails tests, and changes are
154 unlikely to be backported.
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 155
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 156 * --old-passwords: Use the older password scheme (see [[#COMPATIBILITY]], above)
c1704851 » technoweenie 2007-12-08 add a --stateful option (ht... 157
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 158 * --skip-migration: Don't generate a migration file for this model
2366199c » technoweenie 2006-08-01 initial commit of the restf... 159
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 160 * --skip-routes: Don't generate a resource line in @config/routes.rb@
c1704851 » technoweenie 2007-12-08 add a --stateful option (ht... 161
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 162 ***************************************************************************
163 <a id="POST-INSTALL"/> </a>
164 h2. After installing
165
166 The below assumes a Model named 'User' and a Controller named 'Session'; please
167 alter to suit. There are additional security minutae in @notes/README-Tradeoffs@
168 -- only the paranoid or the curious need bother, though.
169
170 * Add these familiar login URLs to your @config/routes.rb@ if you like:
171
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 172 <pre><code>
173 map.signup '/signup', :controller => 'users', :action => 'new'
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 174 map.login '/login', :controller => 'session', :action => 'new'
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 175 map.logout '/logout', :controller => 'session', :action => 'destroy'
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 176 </code></pre>
177
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 178 * With @--include-activation@, also add to your @config/routes.rb@:
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 179
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 180 <pre><code>
181 map.activate '/activate/:activation_code', :controller => 'users', :action => 'activate', :activation_code => nil
182 </code></pre>
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 183
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 184 and add an observer to @config/environment.rb@:
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 185
186 <pre><code>
892c4f72 » crnixon 2008-06-16 fixed pluralization mistake... 187 config.active_record.observers = :user_observer
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 188 </code></pre>
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 189
190 Pay attention, may be this is not an issue for everybody, but if you should
191 have problems, that the sent activation_code does match with that in the
192 database stored, reload your user object before sending its data through email
193 something like:
194
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 195 <pre><code>
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 196 class UserObserver < ActiveRecord::Observer
197 def after_create(user)
198 user.reload
199 UserMailer.deliver_signup_notification(user)
200 end
201 def after_save(user)
202 user.reload
203 UserMailer.deliver_activation(user) if user.recently_activated?
204 end
205 end
206 </code></pre>
207
8a761fe0 » Philip (flip) Kromer 2008-05-16 Documented all the flags, a... 208
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 209 * With @--stateful@, add an observer to config/environment.rb:
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 210
211 <pre><code>
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 212 config.active_record.observers = :user_observer
60a7988e » Philip (flip) Kromer 2008-08-21 Updated README to match wik... 213 </code></pre>
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 214
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 215 and modify the users resource line to read
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 216
8a761fe0 » Philip (flip) Kromer 2008-05-16 Documented all the flags, a... 217 map.resources :users, :member => { :suspend => :put,
218 :unsuspend => :put,
dada879a » bryan-ash 2009-01-11 Reference Cucumber instead ... 219 :purge => :delete }
62216789 » Philip (flip) Kromer 2008-05-17 Added a --skip-routes flag ... 220
68cbb447 » Philip (flip) Kromer 2008-05-19 Organized README, CHANGELOG... 221 * If you use a public repository for your code (such as github, rubyforge,
222 gitorious, etc.) make sure to NOT post your site_keys.rb (add a line like
223 '/config/initializers/site_keys.rb' to your .gitignore or do the svn ignore
224 dance), but make sure you DO keep it backed up somewhere safe.