Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 303 lines (196 sloc) 8.182 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
191 By default, Clearance uses SHA1 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:
192
193 def authenticated?
194 end
195
196 def encrypt_password
197 end
198
4cacef5 @mike-burns Bump to 0.16.0.
mike-burns authored
199 See [lib/clearance/password_strategies/sha1.rb](https://github.com/thoughtbot/clearance/blob/master/lib/clearance/password_strategies/sha1.rb) for the default behavior. 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. Switching password strategies will cause your existing users' passwords to not work.
26933c5 @croaky improving the README's documentation. all overrides should now be doc…
croaky authored
200
201 Once you have an API-compliant module, load it with:
202
203 Clearance.configure do |config|
204 config.password_strategy = MyPasswordStrategy
205 end
206
40362e9 Added blowfish password encryption strategy.
squarism authored
207 For example:
208
209 # default
210 config.password_strategy = Clearance::PasswordStrategies::SHA1
4cacef5 @mike-burns Bump to 0.16.0.
mike-burns authored
211 # Blowfish
40362e9 Added blowfish password encryption strategy.
squarism authored
212 config.password_strategy = Clearance::PasswordStrategies::Blowfish
213
214
d2c3298 @croaky cleaning up the README
croaky authored
215 Optional Cucumber features
216 --------------------------
217
bb2e919 @gabebw typo
gabebw authored
218 Clearance's Cucumber features are dependent on:
d4df728 @croaky explicitly list out dependencies of Cucumber steps
croaky authored
219
220 * Cucumber
221 * Capybara
222 * RSpec
223 * Factory Girl
224
316db9b @croaky better instructions for Cucumber installations
croaky authored
225 As your app evolves, you want to know that authentication still works. If you've
226 installed [Cucumber](http://cukes.info) into your app:
227
228 rails generate cucumber:install
229
230 Then, you can use the Clearance features generator:
d2c3298 @croaky cleaning up the README
croaky authored
231
4f88938 @jferris Fixed references in the README to old generators
jferris authored
232 rails generate clearance:features
5843a08 @croaky updated cucumber instructions in README
croaky authored
233
d41e21f update readme for rails 3
Chad Pytel authored
234 Edit your Gemfile to include:
5843a08 @croaky updated cucumber instructions in README
croaky authored
235
73dcb75 Updated README instructions for Rails 3. Fixed a few typos.
Jeremy Weiskotten authored
236 gem 'factory_girl_rails'
d41e21f update readme for rails 3
Chad Pytel authored
237
dcbff42 @croaky README improvements
croaky authored
238 Edit config/enviroments/test.rb to include the following:
d41e21f update readme for rails 3
Chad Pytel authored
239
73dcb75 Updated README instructions for Rails 3. Fixed a few typos.
Jeremy Weiskotten authored
240 config.action_mailer.default_url_options = { :host => 'localhost:3000' }
5843a08 @croaky updated cucumber instructions in README
croaky authored
241
dcbff42 @croaky README improvements
croaky authored
242 Then run your tests!
243
244 rake
d2c3298 @croaky cleaning up the README
croaky authored
245
f845887 @jferris Perform authentication in Rack middleware
jferris authored
246 Testing
247 -------
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
248
f845887 @jferris Perform authentication in Rack middleware
jferris authored
249 If you want to write Rails functional tests or controller specs with Clearance,
250 you'll need to require the included test helpers and matchers.
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
251
f845887 @jferris Perform authentication in Rack middleware
jferris authored
252 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
253
eaac67b @croaky mimic diesel's naming for clearance/testing. mimic shoulda-matcher's …
croaky authored
254 require 'clearance/testing'
ce48f56 @croaky passing features with test_matchers required in RSpec suites
croaky authored
255
f845887 @jferris Perform authentication in Rack middleware
jferris authored
256 This will make Clearance::Authentication methods work in your controllers
257 during functional tests and provide access to helper methods like:
b2cd877 @croaky legit deny_access matcher
croaky authored
258
259 sign_in
260 sign_in_as(user)
261 sign_out
262
263 And matchers like:
264
265 deny_access
266
267 Example:
268
269 context "a visitor" do
270 before { get :show }
271 it { should deny_access }
272 end
273
274 context "a user" do
275 before do
276 sign_in
277 get :show
278 end
279
280 it { should respond_with(:success) }
281 end
282
a40c6ab @mike-burns Add a document describing how to contribute.
mike-burns authored
283 Contributing
284 ------------
285
286 Please see CONTRIBUTING.md for details.
287
cd12edd update license and credit info
Chad Pytel authored
288 Credits
d2c3298 @croaky cleaning up the README
croaky authored
289 -------
290
cd12edd update license and credit info
Chad Pytel authored
291 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
292
0a406ac use the right name
Chad Pytel authored
293 Clearance is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
d2c3298 @croaky cleaning up the README
croaky authored
294
160d04d @croaky README updates. Includes Rails 3 information and extensions like Clea…
croaky authored
295 Thank you to all [the contributors](https://github.com/thoughtbot/clearance/contributors)!
cd12edd update license and credit info
Chad Pytel authored
296
297 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
298
299 License
300 -------
301
9903447 correct the year
Chad Pytel authored
302 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.