Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 375 lines (258 sloc) 10.191 kB
a79e4bf @croaky Improve README
croaky authored
1 Clearance
d2c3298 @croaky cleaning up the README
croaky authored
2 =========
3
a79e4bf @croaky Improve README
croaky authored
4 [![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.png)](http://travis-ci.org/thoughtbot/clearance?branch=master)
5 [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/thoughtbot/clearance)
6
085dc12 @croaky adding a new #authenticate method at the controller level that can be…
croaky authored
7 Rails authentication & authorization with email & password.
d2c3298 @croaky cleaning up the README
croaky authored
8
c15fa59 @croaky Correct NEWS and README
croaky authored
9 Clearance was extracted out of [Airbrake](http://airbrakeapp.com/).
10 It is intended to be small, simple, well-tested, and easy to override defaults.
d2c3298 @croaky cleaning up the README
croaky authored
11
835cdfe @croaky Clean up Github links in README
croaky authored
12 Use [Github Issues](/thoughtbot/clearance/issues) for help.
cd12edd update license and credit info
Chad Pytel authored
13
835cdfe @croaky Clean up Github links in README
croaky authored
14 Read [CONTRIBUTING.md](/thoughtbot/clearance/blob/master/CONTRIBUTING.md) to contribute.
d2c3298 @croaky cleaning up the README
croaky authored
15
564b859 @croaky Overhaul README.md
croaky authored
16 Install
17 -------
d2c3298 @croaky cleaning up the README
croaky authored
18
a79e4bf @croaky Improve README
croaky authored
19 Clearance is a Rails engine tested against
20 [Rails 3.x](/thoughtbot/clearance/blob/master/Appraisals) on Ruby 1.9.x.
300f965 @qrush Fix readme docs with rails 2 support
qrush authored
21
160d04d @croaky README updates. Includes Rails 3 information and extensions like Clea…
croaky authored
22 Include the gem in your Gemfile:
d2c3298 @croaky cleaning up the README
croaky authored
23
9592586 @croaky Encourage developers to use 1.0.0.rc2
croaky authored
24 gem 'clearance', '1.0.0.rc2'
d2c3298 @croaky cleaning up the README
croaky authored
25
a79e4bf @croaky Improve README
croaky authored
26 Bundle:
27
28 bundle --binstubs
29
30 Make sure the development database exists. Then, run the generator:
d2c3298 @croaky cleaning up the README
croaky authored
31
29d862e @croaky new generator command is rails generate clearance:install. updated RE…
croaky authored
32 rails generate clearance:install
300f965 @qrush Fix readme docs with rails 2 support
qrush authored
33
a79e4bf @croaky Improve README
croaky authored
34 The generator:
d2c3298 @croaky cleaning up the README
croaky authored
35
36 * inserts Clearance::User into your User model
37 * inserts Clearance::Authentication into your ApplicationController
6f53a25 @qrush Small readme typo, thanks r00k
qrush authored
38 * creates a migration that either creates a users table or adds only missing columns
d2c3298 @croaky cleaning up the README
croaky authored
39
a79e4bf @croaky Improve README
croaky authored
40 Then, follow the instructions output from the generator.
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
41
835cdfe @croaky Clean up Github links in README
croaky authored
42 Use the [0.8.x](/thoughtbot/clearance/tree/v0.8.8) series for Rails 2 apps.
dcbff42 @croaky README improvements
croaky authored
43
835cdfe @croaky Clean up Github links in README
croaky authored
44 Use [0.16.3](http://rubygems.org/gems/clearance/versions/0.16.3) for Ruby 1.8.7.
96fdd7a @mike-burns Require Ruby 1.9.2 or anything greater
mike-burns authored
45
564b859 @croaky Overhaul README.md
croaky authored
46 Configure
47 ---------
48
49 Override any of the defaults in `config/initializers/clearance.rb`:
50
51 Clearance.configure do |config|
52 config.cookie_expiration = lambda { 1.year.from_now.utc }
53 config.mailer_sender = 'reply@example.com'
54 config.password_strategy = Clearance::PasswordStrategies::BCrypt
55 config.user_model = User
56 end
d2c3298 @croaky cleaning up the README
croaky authored
57
564b859 @croaky Overhaul README.md
croaky authored
58 Use
59 ---
d2c3298 @croaky cleaning up the README
croaky authored
60
a79e4bf @croaky Improve README
croaky authored
61 Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
62 helpers. For example:
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
63
564b859 @croaky Overhaul README.md
croaky authored
64 - if signed_in?
65 = current_user.email
a79e4bf @croaky Improve README
croaky authored
66 = link_to 'Sign out', sign_out_path, method: :delete
564b859 @croaky Overhaul README.md
croaky authored
67 - else
68 = link_to 'Sign in', sign_in_path
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
69
a79e4bf @croaky Improve README
croaky authored
70 To authenticate a user elsewhere than `sessions/new` (like in an API):
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
71
564b859 @croaky Overhaul README.md
croaky authored
72 User.authenticate 'email@example.com', 'password'
270119c @croaky more details in the README
croaky authored
73
a79e4bf @croaky Improve README
croaky authored
74 When a user resets their password, Clearance delivers them an email. So, you
75 should change the `mailer_sender` default, used in the email's "from" header:
270119c @croaky more details in the README
croaky authored
76
564b859 @croaky Overhaul README.md
croaky authored
77 Clearance.configure do |config|
78 config.mailer_sender = 'reply@example.com'
79 end
270119c @croaky more details in the README
croaky authored
80
a79e4bf @croaky Improve README
croaky authored
81 Use `authorize` to control access in controllers:
82
83 class ArticlesController < ApplicationController
84 before_filter :authorize
85
86 def index
87 current_user.articles
88 end
89 end
90
91 Or, you can authorize users in `config/routes.rb`:
270119c @croaky more details in the README
croaky authored
92
564b859 @croaky Overhaul README.md
croaky authored
93 Blog::Application.routes.draw do
94 constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
a79e4bf @croaky Improve README
croaky authored
95 root to: 'admin'
564b859 @croaky Overhaul README.md
croaky authored
96 end
270119c @croaky more details in the README
croaky authored
97
564b859 @croaky Overhaul README.md
croaky authored
98 constraints Clearance::Constraints::SignedIn.new do
a79e4bf @croaky Improve README
croaky authored
99 root to: 'dashboard'
564b859 @croaky Overhaul README.md
croaky authored
100 end
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
101
564b859 @croaky Overhaul README.md
croaky authored
102 constraints Clearance::Constraints::SignedOut.new do
a79e4bf @croaky Improve README
croaky authored
103 root to: 'marketing'
564b859 @croaky Overhaul README.md
croaky authored
104 end
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
105 end
106
f845887 @jferris Perform authentication in Rack middleware
jferris authored
107 Clearance adds its session to the Rack environment hash so middleware and other
108 Rack applications can interact with it:
109
110 class Bubblegum::Middleware
111 def initialize(app)
112 @app = app
113 end
114
115 def call(env)
116 if env[:clearance].signed_in?
117 env[:clearance].current_user.bubble_gum
118 end
564b859 @croaky Overhaul README.md
croaky authored
119
f845887 @jferris Perform authentication in Rack middleware
jferris authored
120 @app.call(env)
121 end
122 end
123
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
124 Overriding routes
125 -----------------
126
a79e4bf @croaky Improve README
croaky authored
127 See [config/routes.rb](/thoughtbot/clearance/blob/master/config/routes.rb) for
128 the default behavior.
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
129
130 To override a Clearance route, redefine it:
131
a79e4bf @croaky Improve README
croaky authored
132 resource :session, controller: 'sessions'
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
133
134 Overriding controllers
135 ----------------------
136
a79e4bf @croaky Improve README
croaky authored
137 See [app/controllers/clearance](/thoughtbot/clearance/tree/master/app/controllers/clearance)
138 for the default behavior.
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
139
140 To override a Clearance controller, subclass it:
d2c3298 @croaky cleaning up the README
croaky authored
141
564b859 @croaky Overhaul README.md
croaky authored
142 class PasswordsController < Clearance::PasswordsController
d2c3298 @croaky cleaning up the README
croaky authored
143 class SessionsController < Clearance::SessionsController
564b859 @croaky Overhaul README.md
croaky authored
144 class UsersController < Clearance::UsersController
145
146 Then, override public methods:
147
148 passwords#create
149 passwords#edit
150 passwords#new
151 passwords#update
152 sessions#create
153 sessions#destroy
154 sessions#new
155 users#new
156 users#create
157
158 Or, override private methods:
159
160 passwords#find_user_by_id_and_confirmation_token
161 passwords#find_user_for_create
162 passwords#find_user_for_edit
163 passwords#find_user_for_update
164 passwords#flash_failure_when_forbidden
165 passwords#flash_failure_after_create
166 passwords#flash_failure_after_update
167 passwords#forbid_missing_token
168 passwords#forbid_non_existent_user
169 passwords#url_after_create
170 passwords#url_after_update
171 sessions#flash_failure_after_create
172 sessions#url_after_create
173 sessions#url_after_destroy
174 users#flash_failure_after_create
175 users#url_after_create
176 users#user_from_params
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
177
178 Overriding translations
179 -----------------------
180
564b859 @croaky Overhaul README.md
croaky authored
181 All flash messages and email subject lines are stored in
182 [i18n translations](http://guides.rubyonrails.org/i18n.html).
183 Override them like any other translation.
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
184
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
185 Overriding views
186 ----------------
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
187
a79e4bf @croaky Improve README
croaky authored
188 See [app/views](/thoughtbot/clearance/tree/master/app/views) for the default
189 behavior.
564b859 @croaky Overhaul README.md
croaky authored
190
191 To override a view, create your own:
d2c3298 @croaky cleaning up the README
croaky authored
192
2900d73 @croaky Upgrade dependencies
croaky authored
193 app/views/clearance_mailer/change_password.html.erb
194 app/views/passwords/create.html.erb
195 app/views/passwords/edit.html.erb
196 app/views/passwords/new.html.erb
197 app/views/sessions/_form.html.erb
198 app/views/sessions/new.html.erb
199 app/views/users/_form.html.erb
200 app/views/users/new.html.erb
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
201
202 There is a shortcut to copy all Clearance views into your app:
fad9700 @croaky formtastic views are no longer an option. removed dependency in tests…
croaky authored
203
204 rails generate clearance:views
205
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
206 Overriding the model
207 --------------------
208
835cdfe @croaky Clean up Github links in README
croaky authored
209 See [lib/clearance/user.rb](/thoughtbot/clearance/tree/master/lib/clearance/user.rb)
564b859 @croaky Overhaul README.md
croaky authored
210 for the default behavior.
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
211
564b859 @croaky Overhaul README.md
croaky authored
212 To override the model, redefine public methods:
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
213
a79e4bf @croaky Improve README
croaky authored
214 .authenticate(email, password)
215 #forgot_password!
216 #reset_remember_token!
217 #update_password(new_password)
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
218
564b859 @croaky Overhaul README.md
croaky authored
219 Or, redefine private methods:
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
220
a79e4bf @croaky Improve README
croaky authored
221 #downcase_email
222 #email_optional?
223 #generate_confirmation_token
224 #generate_remember_token
225 #password_optional?
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
226
564b859 @croaky Overhaul README.md
croaky authored
227 Overriding the password strategy
228 --------------------------------
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
229
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
230 By default, Clearance uses BCrypt encryption of the user's password.
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
231
a79e4bf @croaky Improve README
croaky authored
232 See [lib/clearance/password_strategies/bcrypt.rb](/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/bcrypt.rb)
233 for the default behavior.
564b859 @croaky Overhaul README.md
croaky authored
234
235 Change your password strategy in `config/initializers/clearance.rb:`
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
236
237 Clearance.configure do |config|
238 config.password_strategy = Clearance::PasswordStrategies::SHA1
239 end
240
564b859 @croaky Overhaul README.md
croaky authored
241 Clearance provides the following strategies:
40362e9 Added blowfish password encryption strategy.
squarism authored
242
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
243 config.password_strategy = Clearance::PasswordStrategies::BCrypt
244 config.password_strategy = Clearance::PasswordStrategies::BCryptMigrationFromSHA1
40362e9 Added blowfish password encryption strategy.
squarism authored
245 config.password_strategy = Clearance::PasswordStrategies::Blowfish
564b859 @croaky Overhaul README.md
croaky authored
246 config.password_strategy = Clearance::PasswordStrategies::SHA1
3746806 Provide router constraints
Arun Agrawal and Gabe Berke-Williams authored
247
564b859 @croaky Overhaul README.md
croaky authored
248 The previous default password strategy was SHA1.
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
249
564b859 @croaky Overhaul README.md
croaky authored
250 Switching password strategies may cause your existing users to not be able to sign in.
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
251
564b859 @croaky Overhaul README.md
croaky authored
252 If you have an existing app that used the old `SHA1` strategy and you
253 want to stay with SHA1, use
835cdfe @croaky Clean up Github links in README
croaky authored
254 [Clearance::PasswordStrategies::SHA1](/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/sha1.rb).
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
255
564b859 @croaky Overhaul README.md
croaky authored
256 If you have an existing app that used the old `SHA1` strategy and you
257 want to switch to BCrypt transparently, use
835cdfe @croaky Clean up Github links in README
croaky authored
258 [Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
259
564b859 @croaky Overhaul README.md
croaky authored
260 The SHA1 and Blowfish password strategies require an additional `salt` column in
261 the `users` table. Run this migration before switching to SHA or Blowfish:
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
262
564b859 @croaky Overhaul README.md
croaky authored
263 class AddSaltToUsers < ActiveRecord::Migration
264 def change
265 add_column :users, :salt, :string, :limit => 128
266 end
6ad1068 @mike-burns Remove the salt from the DB migration
mike-burns authored
267 end
268
564b859 @croaky Overhaul README.md
croaky authored
269 You can write a custom password strategy that has two instance methods:
3746806 Provide router constraints
Arun Agrawal and Gabe Berke-Williams authored
270
564b859 @croaky Overhaul README.md
croaky authored
271 module CustomPasswordStrategy
272 def authenticated?
3746806 Provide router constraints
Arun Agrawal and Gabe Berke-Williams authored
273 end
274
564b859 @croaky Overhaul README.md
croaky authored
275 def password=(new_password)
3746806 Provide router constraints
Arun Agrawal and Gabe Berke-Williams authored
276 end
277 end
278
564b859 @croaky Overhaul README.md
croaky authored
279 Clearance.configure do |config|
280 config.password_strategy = CustomPasswordStrategy
281 end
40362e9 Added blowfish password encryption strategy.
squarism authored
282
d2c3298 @croaky cleaning up the README
croaky authored
283 Optional Cucumber features
284 --------------------------
285
bb2e919 @gabebw typo
gabebw authored
286 Clearance's Cucumber features are dependent on:
d4df728 @croaky explicitly list out dependencies of Cucumber steps
croaky authored
287
288 * Cucumber
289 * Capybara
290 * RSpec
291 * Factory Girl
292
316db9b @croaky better instructions for Cucumber installations
croaky authored
293 As your app evolves, you want to know that authentication still works. If you've
294 installed [Cucumber](http://cukes.info) into your app:
295
296 rails generate cucumber:install
297
298 Then, you can use the Clearance features generator:
d2c3298 @croaky cleaning up the README
croaky authored
299
4f88938 @jferris Fixed references in the README to old generators
jferris authored
300 rails generate clearance:features
5843a08 @croaky updated cucumber instructions in README
croaky authored
301
d41e21f update readme for rails 3
Chad Pytel authored
302 Edit your Gemfile to include:
5843a08 @croaky updated cucumber instructions in README
croaky authored
303
73dcb75 Updated README instructions for Rails 3. Fixed a few typos.
Jeremy Weiskotten authored
304 gem 'factory_girl_rails'
d41e21f update readme for rails 3
Chad Pytel authored
305
a79e4bf @croaky Improve README
croaky authored
306 Edit `config/enviroments/test.rb` to include the following:
d41e21f update readme for rails 3
Chad Pytel authored
307
a79e4bf @croaky Improve README
croaky authored
308 config.action_mailer.default_url_options = { host: 'localhost:3000' }
5843a08 @croaky updated cucumber instructions in README
croaky authored
309
dcbff42 @croaky README improvements
croaky authored
310 Then run your tests!
311
312 rake
d2c3298 @croaky cleaning up the README
croaky authored
313
f845887 @jferris Perform authentication in Rack middleware
jferris authored
314 Testing
315 -------
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
316
f845887 @jferris Perform authentication in Rack middleware
jferris authored
317 If you want to write Rails functional tests or controller specs with Clearance,
564b859 @croaky Overhaul README.md
croaky authored
318 you'll need to require the included test helpers and matchers.
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
319
564b859 @croaky Overhaul README.md
croaky authored
320 For example, in `spec/support/clearance.rb` or `test/test_helper.rb`:
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
321
eaac67b @croaky mimic diesel's naming for clearance/testing. mimic shoulda-matcher's …
croaky authored
322 require 'clearance/testing'
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
323
564b859 @croaky Overhaul README.md
croaky authored
324 This will make `Clearance::Authentication` methods work in your controllers
f845887 @jferris Perform authentication in Rack middleware
jferris authored
325 during functional tests and provide access to helper methods like:
b2cd877 @croaky legit deny_access matcher
croaky authored
326
327 sign_in
328 sign_in_as(user)
329 sign_out
330
331 And matchers like:
332
333 deny_access
334
335 Example:
336
564b859 @croaky Overhaul README.md
croaky authored
337 context 'a visitor' do
338 before do
339 get :show
340 end
341
342 it { should deny_access }
b2cd877 @croaky legit deny_access matcher
croaky authored
343 end
344
564b859 @croaky Overhaul README.md
croaky authored
345 context 'a user' do
b2cd877 @croaky legit deny_access matcher
croaky authored
346 before do
347 sign_in
348 get :show
349 end
350
351 it { should respond_with(:success) }
352 end
353
564b859 @croaky Overhaul README.md
croaky authored
354 You may want to customize the tests:
a40c6ab @mike-burns Add a document describing how to contribute.
mike-burns authored
355
564b859 @croaky Overhaul README.md
croaky authored
356 it { should deny_access }
a79e4bf @croaky Improve README
croaky authored
357 it { should deny_access(flash: 'Denied access.') }
358 it { should deny_access(redirect: sign_in_url) }
a40c6ab @mike-burns Add a document describing how to contribute.
mike-burns authored
359
cd12edd update license and credit info
Chad Pytel authored
360 Credits
d2c3298 @croaky cleaning up the README
croaky authored
361 -------
362
cd12edd update license and credit info
Chad Pytel authored
363 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
364
a79e4bf @croaky Improve README
croaky authored
365 Clearance is maintained by [thoughtbot, inc](http://thoughtbot.com/community)
835cdfe @croaky Clean up Github links in README
croaky authored
366 and [contributors](/thoughtbot/clearance/contributors) like you. Thank you!
cd12edd update license and credit info
Chad Pytel authored
367
368 License
369 -------
370
a79e4bf @croaky Improve README
croaky authored
371 Clearance is copyright © 2009-2012 thoughtbot. It is free software, and may be
372 redistributed under the terms specified in the `LICENSE` file.
2900d73 @croaky Upgrade dependencies
croaky authored
373
374 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
Something went wrong with that request. Please try again.