Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 345 lines (230 sloc) 9.959 kB
91674c6 @croaky [#180] Use Travis CI
croaky authored
1 Clearance [![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.png)](http://travis-ci.org/thoughtbot/clearance?branch=master)
d2c3298 @croaky cleaning up the README
croaky authored
2 =========
3
085dc12 @croaky adding a new #authenticate method at the controller level that can be…
croaky authored
4 Rails authentication & authorization with email & password.
d2c3298 @croaky cleaning up the README
croaky authored
5
1f1e19d @croaky fixed broken youtube link in README. hat tip smix for reporting this …
croaky authored
6 [We have clearance, Clarence.](http://www.youtube.com/watch?v=fVq4_HhBK8Y)
d2c3298 @croaky cleaning up the README
croaky authored
7
ff404c8 @neilparikh Updated link on README.
neilparikh authored
8 Clearance was extracted out of [Airbrake](http://airbrakeapp.com/).
cd12edd update license and credit info
Chad Pytel authored
9
d2c3298 @croaky cleaning up the README
croaky authored
10 Help
11 ----
12
dcbff42 @croaky README improvements
croaky authored
13 * [Documentation](http://rdoc.info/gems/clearance) at RDoc.info.
085dc12 @croaky adding a new #authenticate method at the controller level that can be…
croaky authored
14 * [Patches and bugs](http://github.com/thoughtbot/clearance/issues) at Github Issues.
15 * [Mailing list](http://groups.google.com/group/thoughtbot-clearance) at Google Groups.
d2c3298 @croaky cleaning up the README
croaky authored
16
17 Installation
18 ------------
19
e084e6b @gabebw List the correct Rails versions in the README.
gabebw authored
20 Clearance is a Rails engine for Rails 3. It is currently tested against Rails
21 3.0.12, 3.1.4, and 3.2.3.
300f965 @qrush Fix readme docs with rails 2 support
qrush authored
22
160d04d @croaky README updates. Includes Rails 3 information and extensions like Clea…
croaky authored
23 Include the gem in your Gemfile:
d2c3298 @croaky cleaning up the README
croaky authored
24
300f965 @qrush Fix readme docs with rails 2 support
qrush authored
25 gem "clearance"
d2c3298 @croaky cleaning up the README
croaky authored
26
6aae67e @croaky altered install instructions to tell users to uninstall old versions.…
croaky authored
27 Make sure the development database exists, then run the generator:
d2c3298 @croaky cleaning up the README
croaky authored
28
29d862e @croaky new generator command is rails generate clearance:install. updated RE…
croaky authored
29 rails generate clearance:install
300f965 @qrush Fix readme docs with rails 2 support
qrush authored
30
d2c3298 @croaky cleaning up the README
croaky authored
31 This:
32
33 * inserts Clearance::User into your User model
34 * inserts Clearance::Authentication into your ApplicationController
6f53a25 @qrush Small readme typo, thanks r00k
qrush authored
35 * creates a migration that either creates a users table or adds only missing columns
d2c3298 @croaky cleaning up the README
croaky authored
36
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
37 Follow the instructions that are output from the generator.
38
dcbff42 @croaky README improvements
croaky authored
39 Use the [0.8.x](https://github.com/thoughtbot/clearance/tree/v0.8.8)
40 series of Clearance if you have a Rails 2 app.
41
d2c3298 @croaky cleaning up the README
croaky authored
42 Usage
43 -----
44
085dc12 @croaky adding a new #authenticate method at the controller level that can be…
croaky authored
45 If you want to authorize users for a controller action, use the authorize
d2c3298 @croaky cleaning up the README
croaky authored
46 method in a before_filter.
47
48 class WidgetsController < ApplicationController
085dc12 @croaky adding a new #authenticate method at the controller level that can be…
croaky authored
49 before_filter :authorize
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
50
d2c3298 @croaky cleaning up the README
croaky authored
51 def index
52 @widgets = Widget.all
53 end
54 end
55
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
56 If you want to reference the current user in a controller, view, or helper, use
57 the current_user method.
58
59 def index
60 current_user.articles
61 end
62
270119c @croaky more details in the README
croaky authored
63 If you want to know whether the current user is signed in or out, you can use
64 these methods in controllers, views, or helpers:
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
65
270119c @croaky more details in the README
croaky authored
66 signed_in?
67 signed_out?
68
69 Typically, you want to have something like this in your app, maybe in a layout:
70
71 <% if signed_in? %>
72 <%= current_user.email %>
73 <%= link_to "Sign out", sign_out_path, :method => :delete %>
74 <% else %>
75 <%= link_to "Sign in", sign_in_path %>
76 <% end %>
77
78 If you ever want to authenticate the user some place other than sessions/new,
79 maybe in an API:
80
81 User.authenticate("email@example.com", "password")
82
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
83 Clearance will deliver one email on your app's behalf: when a user resets their password. Therefore, you should change the default email address that email comes from:
84
85 # config/initializers/clearance.rb
86 Clearance.configure do |config|
87 config.mailer_sender = "me@example.com"
88 end
89
f845887 @jferris Perform authentication in Rack middleware
jferris authored
90 Rack
91 ----
92
93 Clearance adds its session to the Rack environment hash so middleware and other
94 Rack applications can interact with it:
95
96 class Bubblegum::Middleware
97 def initialize(app)
98 @app = app
99 end
100
101 def call(env)
102 if env[:clearance].signed_in?
103 env[:clearance].current_user.bubble_gum
104 end
105 @app.call(env)
106 end
107 end
108
109
270119c @croaky more details in the README
croaky authored
110 Overriding defaults
111 -------------------
112
113 Clearance is intended to be small, simple, well-tested, and easy to override defaults.
eaac67b @croaky mimic diesel's naming for clearance/testing. mimic shoulda-matcher's …
croaky authored
114
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
115 Overriding routes
116 -----------------
117
118 See [config/routes.rb](https://github.com/thoughtbot/clearance/blob/master/config/routes.rb) for the default behavior.
119
120 To override a Clearance route, redefine it:
121
122 resource :session, :controller => 'sessions'
123
124 Overriding controllers
125 ----------------------
126
127 See [app/controllers/clearance](https://github.com/thoughtbot/clearance/tree/master/app/controllers/clearance) for the default behavior.
128
129 To override a Clearance controller, subclass it:
d2c3298 @croaky cleaning up the README
croaky authored
130
131 class SessionsController < Clearance::SessionsController
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
132 def new
133 # my special new action
134 end
4a3de1b @croaky clarifications to the README based on feedback
croaky authored
135
d2c3298 @croaky cleaning up the README
croaky authored
136 def url_after_create
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
137 my_special_path
d2c3298 @croaky cleaning up the README
croaky authored
138 end
139 end
140
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
141 You may want to override entire actions:
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
142
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
143 def new
144 end
145
146 Or, you may want to override private methods that actions use:
147
148 url_after_create
149 url_after_update
150 url_after_destroy
151 flash_failure_after_create
152 flash_failure_after_update
153 flash_failure_when_forbidden
154 forbid_missing_token
155 forbid_non_existent_user
156
157 Overriding translations
158 -----------------------
159
160 All flash messages and email subject lines are stored in [i18n translations](http://guides.rubyonrails.org/i18n.html). Override them like any other translation.
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
161
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
162 Overriding views
163 ----------------
9b091f5 @croaky better documentation on customizing controllers/actions/routes
croaky authored
164
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
165 See [app/views](https://github.com/thoughtbot/clearance/tree/master/app/views) for the default behavior.
d2c3298 @croaky cleaning up the README
croaky authored
166
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
167 To override those **views**, create them in your own `app/views` directory.
168
169 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
170
171 rails generate clearance:views
172
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
173 Overriding the model
174 --------------------
175
176 If you want to override the **model** behavior, you can include sub-modules of `Clearance::User`:
177
178 extend Clearance::User::ClassMethods
179 include Clearance::User::Validations
180 include Clearance::User::Callbacks
181
182 `ClassMethods` contains the `User.authenticate(email, password)` method.
183
184 `Validations` contains validations for email and password.
185
186 `Callbacks` contains `ActiveRecord` callbacks downcasing the email and generating a remember token.
187
188 Overriding the password strategy
189 --------------------------------
190
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
191 By default, Clearance uses BCrypt encryption of the user's password. You can provide your own password strategy by creating a module that conforms to an API of two instance methods:
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
192
193 def authenticated?
194 end
195
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
196 def password=(new_password)
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
197 end
198
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
199 The previous default password strategy was SHA1. To keep using SHA1, use this
200 code:
201
202 Clearance.configure do |config|
203 config.password_strategy = Clearance::PasswordStrategies::SHA1
204 end
205
206 See [lib/clearance/password_strategies/bcrypt.rb](https://github.com/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/bcrypt.rb) for the default behavior.
207 Also see [lib/clearance/password_strategies/blowfish.rb](https://github.com/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/blowfish.rb) for another password strategy.
208 Switching password strategies will cause your existing users' passwords to not
209 work. If you are currently using the SHA1 strategy (the previous default), and
210 want to transparently switch to BCrypt, use the [BCryptMigrationFromSHA1 strategy](https://github.com/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
211
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
212
213 Once you have an API-compliant module, load it with:
214
215 Clearance.configure do |config|
216 config.password_strategy = MyPasswordStrategy
217 end
218
40362e9 Added blowfish password encryption strategy.
squarism authored
219 For example:
220
221 # default
be37c35 BCrypt for passwords
Dan Croak and Gabe Berke-Williams authored
222 config.password_strategy = Clearance::PasswordStrategies::BCrypt
223 # use this strategy if you used to use SHA1, and now you want to use BCrypt
224 config.password_strategy = Clearance::PasswordStrategies::BCryptMigrationFromSHA1
225 # SHA1 (the previous default)
40362e9 Added blowfish password encryption strategy.
squarism authored
226 config.password_strategy = Clearance::PasswordStrategies::SHA1
4cacef5 @mike-burns Bump to 0.16.0.
mike-burns authored
227 # Blowfish
40362e9 Added blowfish password encryption strategy.
squarism authored
228 config.password_strategy = Clearance::PasswordStrategies::Blowfish
3746806 Provide router constraints
Arun Agrawal and Gabe Berke-Williams authored
229
230 Routing Constraints
231 -------------------
232
233 Clearance ships with Rails [routing constraints](http://guides.rubyonrails.org/routing.html#advanced-constraints).
234 These allow you to check if a user is signed in or signed out before they hit your controller - the check is moved down the stack.
235 You can use them like this:
236
237 SweetBlog::Application.routes.draw do
238 # Signed-in admin users use this root path
239 constraints(Clearance::Constraints::SignedIn.new {|user| user.admin?}) do
240 root :to => 'admins/dashboard#index'
241 end
242
243 # Signed-in non-admin users use this root path
244 constraints(Clearance::Constraints::SignedIn.new) do
245 root :to => 'organizations#show'
246 end
247
248 # Signed-out users users use this fallback root path
249 constraints(Clearance::Constraints::SignedOut.new) do
250 root :to => 'high_voltage/pages#show', :id => 'home'
251 end
252 end
253
254 Note that `Clearance::Constraints::SignedIn` yields a signed-in user object so
255 that you can perform additional checks.
40362e9 Added blowfish password encryption strategy.
squarism authored
256
d2c3298 @croaky cleaning up the README
croaky authored
257 Optional Cucumber features
258 --------------------------
259
bb2e919 @gabebw typo
gabebw authored
260 Clearance's Cucumber features are dependent on:
d4df728 @croaky explicitly list out dependencies of Cucumber steps
croaky authored
261
262 * Cucumber
263 * Capybara
264 * RSpec
265 * Factory Girl
266
316db9b @croaky better instructions for Cucumber installations
croaky authored
267 As your app evolves, you want to know that authentication still works. If you've
268 installed [Cucumber](http://cukes.info) into your app:
269
270 rails generate cucumber:install
271
272 Then, you can use the Clearance features generator:
d2c3298 @croaky cleaning up the README
croaky authored
273
4f88938 @jferris Fixed references in the README to old generators
jferris authored
274 rails generate clearance:features
5843a08 @croaky updated cucumber instructions in README
croaky authored
275
d41e21f update readme for rails 3
Chad Pytel authored
276 Edit your Gemfile to include:
5843a08 @croaky updated cucumber instructions in README
croaky authored
277
73dcb75 Updated README instructions for Rails 3. Fixed a few typos.
Jeremy Weiskotten authored
278 gem 'factory_girl_rails'
d41e21f update readme for rails 3
Chad Pytel authored
279
dcbff42 @croaky README improvements
croaky authored
280 Edit config/enviroments/test.rb to include the following:
d41e21f update readme for rails 3
Chad Pytel authored
281
73dcb75 Updated README instructions for Rails 3. Fixed a few typos.
Jeremy Weiskotten authored
282 config.action_mailer.default_url_options = { :host => 'localhost:3000' }
5843a08 @croaky updated cucumber instructions in README
croaky authored
283
dcbff42 @croaky README improvements
croaky authored
284 Then run your tests!
285
286 rake
d2c3298 @croaky cleaning up the README
croaky authored
287
f845887 @jferris Perform authentication in Rack middleware
jferris authored
288 Testing
289 -------
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
290
f845887 @jferris Perform authentication in Rack middleware
jferris authored
291 If you want to write Rails functional tests or controller specs with Clearance,
292 you'll need to require the included test helpers and matchers.
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
293
f845887 @jferris Perform authentication in Rack middleware
jferris authored
294 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
295
eaac67b @croaky mimic diesel's naming for clearance/testing. mimic shoulda-matcher's …
croaky authored
296 require 'clearance/testing'
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
297
f845887 @jferris Perform authentication in Rack middleware
jferris authored
298 This will make Clearance::Authentication methods work in your controllers
299 during functional tests and provide access to helper methods like:
b2cd877 @croaky legit deny_access matcher
croaky authored
300
301 sign_in
302 sign_in_as(user)
303 sign_out
304
305 And matchers like:
306
307 deny_access
308
309 Example:
310
311 context "a visitor" do
312 before { get :show }
313 it { should deny_access }
314 end
315
316 context "a user" do
317 before do
318 sign_in
319 get :show
320 end
321
322 it { should respond_with(:success) }
323 end
324
a40c6ab @mike-burns Add a document describing how to contribute.
mike-burns authored
325 Contributing
326 ------------
327
328 Please see CONTRIBUTING.md for details.
329
cd12edd update license and credit info
Chad Pytel authored
330 Credits
d2c3298 @croaky cleaning up the README
croaky authored
331 -------
332
cd12edd update license and credit info
Chad Pytel authored
333 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
334
0a406ac use the right name
Chad Pytel authored
335 Clearance is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
d2c3298 @croaky cleaning up the README
croaky authored
336
160d04d @croaky README updates. Includes Rails 3 information and extensions like Clea…
croaky authored
337 Thank you to all [the contributors](https://github.com/thoughtbot/clearance/contributors)!
cd12edd update license and credit info
Chad Pytel authored
338
339 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
340
341 License
342 -------
343
9903447 correct the year
Chad Pytel authored
344 Clearance is Copyright © 2009-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the LICENSE file.
Something went wrong with that request. Please try again.