clearance 1.8.0 → 1.13.0
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of clearance might be problematic. Click here for more details.
- checksums.yaml +4 -4
- data/.gitignore +2 -0
- data/.travis.yml +24 -6
- data/.yardopts +6 -0
- data/Appraisals +12 -4
- data/CONTRIBUTING.md +4 -1
- data/Gemfile +2 -2
- data/Gemfile.lock +87 -85
- data/NEWS.md +672 -311
- data/README.md +185 -330
- data/app/controllers/clearance/passwords_controller.rb +25 -19
- data/app/controllers/clearance/sessions_controller.rb +17 -4
- data/app/controllers/clearance/users_controller.rb +10 -4
- data/app/mailers/clearance_mailer.rb +2 -3
- data/app/views/clearance_mailer/change_password.html.erb +6 -3
- data/app/views/clearance_mailer/change_password.text.erb +5 -0
- data/app/views/layouts/application.html.erb +2 -2
- data/app/views/passwords/create.html.erb +1 -1
- data/app/views/passwords/edit.html.erb +2 -2
- data/app/views/passwords/new.html.erb +2 -2
- data/app/views/sessions/_form.html.erb +2 -2
- data/app/views/sessions/new.html.erb +1 -1
- data/app/views/users/new.html.erb +2 -2
- data/bin/setup +6 -2
- data/config/locales/clearance.en.yml +6 -0
- data/db/migrate/20110111224543_create_clearance_users.rb +1 -1
- data/gemfiles/{rails3.2.gemfile → rails32.gemfile} +1 -1
- data/gemfiles/{rails4.0.gemfile → rails40.gemfile} +2 -2
- data/gemfiles/{rails4.1.gemfile → rails41.gemfile} +2 -2
- data/gemfiles/{rails4.2.gemfile → rails42.gemfile} +2 -2
- data/gemfiles/rails50.gemfile +19 -0
- data/lib/clearance/authentication.rb +52 -1
- data/lib/clearance/authorization.rb +47 -4
- data/lib/clearance/back_door.rb +1 -0
- data/lib/clearance/configuration.rb +127 -15
- data/lib/clearance/constraints/signed_in.rb +21 -0
- data/lib/clearance/constraints/signed_out.rb +12 -0
- data/lib/clearance/constraints.rb +12 -0
- data/lib/clearance/controller.rb +13 -0
- data/lib/clearance/default_sign_in_guard.rb +17 -0
- data/lib/clearance/engine.rb +24 -4
- data/lib/clearance/password_strategies/bcrypt.rb +9 -2
- data/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb +19 -0
- data/lib/clearance/password_strategies/blowfish.rb +17 -0
- data/lib/clearance/password_strategies/sha1.rb +17 -0
- data/lib/clearance/password_strategies.rb +13 -0
- data/lib/clearance/rack_session.rb +13 -0
- data/lib/clearance/rspec.rb +15 -4
- data/lib/clearance/session.rb +46 -1
- data/lib/clearance/session_status.rb +7 -0
- data/lib/clearance/sign_in_guard.rb +65 -0
- data/lib/clearance/test_unit.rb +3 -3
- data/lib/clearance/testing/controller_helpers.rb +44 -0
- data/lib/clearance/testing/deny_access_matcher.rb +35 -1
- data/lib/clearance/testing/helpers.rb +9 -25
- data/lib/clearance/testing/view_helpers.rb +32 -0
- data/lib/clearance/token.rb +7 -0
- data/lib/clearance/user.rb +159 -0
- data/lib/clearance/version.rb +1 -1
- data/lib/clearance.rb +2 -0
- data/lib/generators/clearance/install/install_generator.rb +13 -3
- data/lib/generators/clearance/install/templates/db/migrate/add_clearance_to_users.rb +3 -3
- data/lib/generators/clearance/install/templates/db/migrate/create_users.rb +2 -2
- data/lib/generators/clearance/routes/routes_generator.rb +23 -0
- data/lib/generators/clearance/routes/templates/routes.rb +7 -7
- data/lib/generators/clearance/specs/templates/features/clearance/user_signs_out_spec.rb.tt +1 -1
- data/lib/generators/clearance/specs/templates/features/clearance/visitor_resets_password_spec.rb.tt +12 -2
- data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_in_spec.rb.tt +1 -1
- data/lib/generators/clearance/specs/templates/features/clearance/visitor_signs_up_spec.rb.tt +1 -1
- data/lib/generators/clearance/specs/templates/features/clearance/visitor_updates_password_spec.rb.tt +1 -1
- data/spec/acceptance/clearance_installation_spec.rb +4 -1
- data/spec/app_templates/config/initializers/clearance.rb +2 -0
- data/spec/app_templates/testapp/app/controllers/home_controller.rb +5 -1
- data/spec/app_templates/testapp/config/initializers/action_mailer.rb +1 -3
- data/spec/clearance/controller_spec.rb +11 -0
- data/spec/clearance/rack_session_spec.rb +5 -5
- data/spec/clearance/testing/{helpers_spec.rb → controller_helpers_spec.rb} +12 -12
- data/spec/clearance/testing/view_helpers_spec.rb +37 -0
- data/spec/configuration_spec.rb +24 -0
- data/spec/controllers/apis_controller_spec.rb +6 -2
- data/spec/controllers/forgeries_controller_spec.rb +6 -1
- data/spec/controllers/passwords_controller_spec.rb +1 -11
- data/spec/controllers/permissions_controller_spec.rb +13 -3
- data/spec/controllers/sessions_controller_spec.rb +4 -4
- data/spec/dummy/app/controllers/application_controller.rb +5 -1
- data/spec/dummy/application.rb +4 -0
- data/spec/generators/clearance/install/install_generator_spec.rb +15 -3
- data/spec/generators/clearance/routes/routes_generator_spec.rb +5 -1
- data/spec/generators/clearance/views/views_generator_spec.rb +11 -10
- data/spec/helpers/helper_helpers_spec.rb +10 -0
- data/spec/mailers/clearance_mailer_spec.rb +13 -19
- data/spec/password_strategies/bcrypt_migration_from_sha1_spec.rb +6 -0
- data/spec/password_strategies/blowfish_spec.rb +6 -0
- data/spec/password_strategies/sha1_spec.rb +6 -0
- data/spec/spec_helper.rb +7 -0
- data/spec/support/generator_spec_helpers.rb +4 -0
- data/spec/support/http_method_shim.rb +23 -0
- data/spec/user_spec.rb +9 -0
- data/spec/views/view_helpers_spec.rb +10 -0
- metadata +19 -8
data/README.md
CHANGED
@@ -1,14 +1,13 @@
|
|
1
|
-
Clearance
|
2
|
-
=========
|
1
|
+
# Clearance
|
3
2
|
|
4
3
|
[![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.svg)](http://travis-ci.org/thoughtbot/clearance?branch=master)
|
5
4
|
[![Code Climate](https://codeclimate.com/github/thoughtbot/clearance.svg)](https://codeclimate.com/github/thoughtbot/clearance)
|
5
|
+
[![Documentation Quality](https://inch-ci.org/github/thoughtbot/clearance.svg?branch=master)](https://inch-ci.org/github/thoughtbot/clearance)
|
6
6
|
|
7
7
|
Rails authentication with email & password.
|
8
8
|
|
9
|
-
Clearance
|
10
|
-
|
11
|
-
defaults.
|
9
|
+
Clearance is intended to be small, simple, and well-tested. It has opinionated
|
10
|
+
defaults but is intended to be easy to override.
|
12
11
|
|
13
12
|
Please use [GitHub Issues] to report bugs. If you have a question about the
|
14
13
|
library, please use the `clearance` tag on [Stack Overflow]. This tag is
|
@@ -17,45 +16,33 @@ monitored by contributors.
|
|
17
16
|
[GitHub Issues]: https://github.com/thoughtbot/clearance/issues
|
18
17
|
[Stack Overflow]: http://stackoverflow.com/questions/tagged/clearance
|
19
18
|
|
20
|
-
|
21
|
-
|
22
|
-
Install
|
23
|
-
-------
|
19
|
+
## Getting Started
|
24
20
|
|
25
21
|
Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
|
26
|
-
It works with Rails 4 and Ruby 2.
|
27
22
|
|
28
|
-
|
23
|
+
You can add it to your Gemfile with:
|
29
24
|
|
30
|
-
```
|
25
|
+
```sh
|
31
26
|
gem 'clearance'
|
32
27
|
```
|
33
28
|
|
34
|
-
|
35
|
-
|
36
|
-
bundle install
|
37
|
-
|
38
|
-
Make sure the development database exists. Then, run the generator:
|
39
|
-
|
40
|
-
rails generate clearance:install
|
29
|
+
Run the bundle command to install it.
|
41
30
|
|
42
|
-
|
31
|
+
After you install Clearance, you need to run the generator:
|
43
32
|
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
columns
|
48
|
-
|
49
|
-
Then, follow the instructions output from the generator.
|
33
|
+
```sh
|
34
|
+
$ rails generate clearance:install
|
35
|
+
```
|
50
36
|
|
51
|
-
|
52
|
-
Rails 2 apps.
|
37
|
+
The Clearance install generator:
|
53
38
|
|
54
|
-
|
55
|
-
|
39
|
+
* Inserts `Clearance::User` into your `User` model
|
40
|
+
* Inserts `Clearance::Controller` into your `ApplicationController`
|
41
|
+
* Creates an initializer file to allow further configuration.
|
42
|
+
* Creates a migration file that either create a users table or adds any necessary
|
43
|
+
columns to the existing table.
|
56
44
|
|
57
|
-
Configure
|
58
|
-
---------
|
45
|
+
## Configure
|
59
46
|
|
60
47
|
Override any of these defaults in `config/initializers/clearance.rb`:
|
61
48
|
|
@@ -77,40 +64,15 @@ Clearance.configure do |config|
|
|
77
64
|
end
|
78
65
|
```
|
79
66
|
|
80
|
-
Use
|
81
|
-
---
|
67
|
+
## Use
|
82
68
|
|
83
|
-
|
84
|
-
helpers. For example:
|
69
|
+
### Access Control
|
85
70
|
|
86
|
-
|
87
|
-
- if signed_in?
|
88
|
-
= current_user.email
|
89
|
-
= button_to 'Sign out', sign_out_path, method: :delete
|
90
|
-
- else
|
91
|
-
= link_to 'Sign in', sign_in_path
|
92
|
-
```
|
93
|
-
|
94
|
-
To authenticate a user elsewhere than `sessions/new` (like in an API):
|
95
|
-
|
96
|
-
```ruby
|
97
|
-
User.authenticate 'email@example.com', 'password'
|
98
|
-
```
|
99
|
-
|
100
|
-
When a user resets their password, Clearance delivers them an email. So, you
|
101
|
-
should change the `mailer_sender` default, used in the email's "from" header:
|
102
|
-
|
103
|
-
```ruby
|
104
|
-
Clearance.configure do |config|
|
105
|
-
config.mailer_sender = 'reply@example.com'
|
106
|
-
end
|
107
|
-
```
|
108
|
-
|
109
|
-
Use `require_login` to control access in controllers:
|
71
|
+
Use the `require_login` filter to control access to controller actions.
|
110
72
|
|
111
73
|
```ruby
|
112
74
|
class ArticlesController < ApplicationController
|
113
|
-
|
75
|
+
before_action :require_login
|
114
76
|
|
115
77
|
def index
|
116
78
|
current_user.articles
|
@@ -118,7 +80,8 @@ class ArticlesController < ApplicationController
|
|
118
80
|
end
|
119
81
|
```
|
120
82
|
|
121
|
-
|
83
|
+
Clearance also provides routing constraints that can be used to control access
|
84
|
+
at the routing layer:
|
122
85
|
|
123
86
|
```ruby
|
124
87
|
Blog::Application.routes.draw do
|
@@ -136,6 +99,33 @@ Blog::Application.routes.draw do
|
|
136
99
|
end
|
137
100
|
```
|
138
101
|
|
102
|
+
### Helper Methods
|
103
|
+
|
104
|
+
Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
|
105
|
+
helpers. For example:
|
106
|
+
|
107
|
+
```erb
|
108
|
+
<% if signed_in? %>
|
109
|
+
<%= current_user.email %>
|
110
|
+
<%= button_to "Sign out", sign_out_path, method: :delete %>
|
111
|
+
<% else %>
|
112
|
+
<%= link_to "Sign in", sign_in_path %>
|
113
|
+
<% end %>
|
114
|
+
```
|
115
|
+
|
116
|
+
### Password Resets
|
117
|
+
|
118
|
+
When a user resets their password, Clearance delivers them an email. You
|
119
|
+
should change the `mailer_sender` default, used in the email's "from" header:
|
120
|
+
|
121
|
+
```ruby
|
122
|
+
Clearance.configure do |config|
|
123
|
+
config.mailer_sender = 'reply@example.com'
|
124
|
+
end
|
125
|
+
```
|
126
|
+
|
127
|
+
### Integrating with Rack Applications
|
128
|
+
|
139
129
|
Clearance adds its session to the Rack environment hash so middleware and other
|
140
130
|
Rack applications can interact with it:
|
141
131
|
|
@@ -155,28 +145,27 @@ class Bubblegum::Middleware
|
|
155
145
|
end
|
156
146
|
```
|
157
147
|
|
158
|
-
Overriding
|
159
|
-
|
148
|
+
## Overriding Clearance
|
149
|
+
|
150
|
+
### Routes
|
160
151
|
|
161
152
|
See [config/routes.rb](/config/routes.rb) for the default set of routes.
|
162
153
|
|
163
|
-
|
164
|
-
|
165
|
-
all clearance routes, giving the user full control over routing and URL design.
|
154
|
+
As of Clearance 1.5 it is recommended that you disable Clearance routes and take
|
155
|
+
full control over routing and URL design.
|
166
156
|
|
167
157
|
To disable the routes, set `config.routes = false`. You can optionally run
|
168
158
|
`rails generate clearance:routes` to dump a copy of the default routes into your
|
169
159
|
application for modification.
|
170
160
|
|
171
|
-
|
172
|
-
|
173
|
-
Overriding controllers
|
174
|
-
----------------------
|
161
|
+
### Controllers
|
175
162
|
|
176
163
|
See [app/controllers/clearance](/app/controllers/clearance) for the default
|
177
|
-
behavior.
|
164
|
+
behavior. Many protected methods were extracted in these controllers in an
|
165
|
+
attempt to make overrides and hooks simpler.
|
178
166
|
|
179
|
-
To override a Clearance controller, subclass it
|
167
|
+
To override a Clearance controller, subclass it and update the routes to
|
168
|
+
point to your new controller (see the "Routes" section).
|
180
169
|
|
181
170
|
```ruby
|
182
171
|
class PasswordsController < Clearance::PasswordsController
|
@@ -184,203 +173,84 @@ class SessionsController < Clearance::SessionsController
|
|
184
173
|
class UsersController < Clearance::UsersController
|
185
174
|
```
|
186
175
|
|
187
|
-
|
188
|
-
|
189
|
-
Then, override public methods:
|
190
|
-
|
191
|
-
passwords#create
|
192
|
-
passwords#edit
|
193
|
-
passwords#new
|
194
|
-
passwords#update
|
195
|
-
sessions#create
|
196
|
-
sessions#destroy
|
197
|
-
sessions#new
|
198
|
-
users#create
|
199
|
-
users#new
|
200
|
-
|
201
|
-
Or, override private methods:
|
202
|
-
|
203
|
-
passwords#find_user_by_id_and_confirmation_token
|
204
|
-
passwords#find_user_for_create
|
205
|
-
passwords#find_user_for_edit
|
206
|
-
passwords#find_user_for_update
|
207
|
-
passwords#flash_failure_after_create
|
208
|
-
passwords#flash_failure_after_update
|
209
|
-
passwords#flash_failure_when_forbidden
|
210
|
-
passwords#forbid_missing_token
|
211
|
-
passwords#forbid_non_existent_user
|
212
|
-
passwords#url_after_create
|
213
|
-
passwords#url_after_update
|
214
|
-
sessions#url_after_create
|
215
|
-
sessions#url_after_destroy
|
216
|
-
users#flash_failure_after_create
|
217
|
-
users#url_after_create
|
218
|
-
users#user_from_params
|
219
|
-
users#user_params
|
220
|
-
|
221
|
-
All of these controller methods redirect to `'/'` by default:
|
222
|
-
|
223
|
-
passwords#url_after_update
|
224
|
-
sessions#url_after_create
|
225
|
-
sessions#url_for_signed_in_users
|
226
|
-
users#url_after_create
|
227
|
-
application#url_after_denied_access_when_signed_in
|
228
|
-
|
229
|
-
To override them all at once, change the global configuration:
|
230
|
-
|
231
|
-
```ruby
|
232
|
-
Clearance.configure do |config|
|
233
|
-
config.redirect_url = '/overridden'
|
234
|
-
end
|
235
|
-
```
|
236
|
-
|
237
|
-
Overriding translations
|
238
|
-
-----------------------
|
239
|
-
|
240
|
-
All flash messages and email subject lines are stored in
|
241
|
-
[i18n translations](http://guides.rubyonrails.org/i18n.html).
|
242
|
-
Override them like any other translation.
|
243
|
-
|
244
|
-
See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
|
245
|
-
default behavior.
|
176
|
+
### Redirects
|
246
177
|
|
247
|
-
|
248
|
-
|
178
|
+
All of these controller methods redirect to
|
179
|
+
`Clearance.configuration.redirect_url` (which is `/` by default):
|
249
180
|
|
250
|
-
|
251
|
-
|
252
|
-
|
253
|
-
|
254
|
-
|
255
|
-
|
256
|
-
Clearance::SessionsController.layout 'my_sessions_layout'
|
257
|
-
Clearance::UsersController.layout 'my_admin_layout'
|
181
|
+
```
|
182
|
+
passwords#url_after_update
|
183
|
+
sessions#url_after_create
|
184
|
+
sessions#url_for_signed_in_users
|
185
|
+
users#url_after_create
|
186
|
+
application#url_after_denied_access_when_signed_in
|
258
187
|
```
|
259
188
|
|
260
|
-
|
261
|
-
|
262
|
-
|
263
|
-
See [app/views](/app/views) for the default behavior.
|
264
|
-
|
265
|
-
To override a view, create your own:
|
266
|
-
|
267
|
-
app/views/clearance_mailer/change_password.html.erb
|
268
|
-
app/views/passwords/create.html.erb
|
269
|
-
app/views/passwords/edit.html.erb
|
270
|
-
app/views/passwords/new.html.erb
|
271
|
-
app/views/sessions/_form.html.erb
|
272
|
-
app/views/sessions/new.html.erb
|
273
|
-
app/views/users/_form.html.erb
|
274
|
-
app/views/users/new.html.erb
|
275
|
-
|
276
|
-
There is a shortcut to copy all Clearance views into your app:
|
277
|
-
|
278
|
-
rails generate clearance:views
|
279
|
-
|
280
|
-
Overriding the model
|
281
|
-
--------------------
|
282
|
-
|
283
|
-
See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
|
284
|
-
|
285
|
-
To override the model, redefine public methods:
|
286
|
-
|
287
|
-
User.authenticate(email, password)
|
288
|
-
User#forgot_password!
|
289
|
-
User#reset_remember_token!
|
290
|
-
User#update_password(new_password)
|
291
|
-
|
292
|
-
Or, redefine private methods:
|
293
|
-
|
294
|
-
User#email_optional?
|
295
|
-
User#generate_confirmation_token
|
296
|
-
User#generate_remember_token
|
297
|
-
User#normalize_email
|
298
|
-
User#password_optional?
|
189
|
+
To override them all at once, change the global configuration of `redirect_url`.
|
190
|
+
To change individual URLs, override the appropriate method.
|
299
191
|
|
300
|
-
|
301
|
-
|
192
|
+
`application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
|
193
|
+
Override this method to change this.
|
302
194
|
|
303
|
-
|
195
|
+
### Views
|
304
196
|
|
305
|
-
See
|
306
|
-
[lib/clearance/password_strategies/bcrypt.rb](/lib/clearance/password_strategies/bcrypt.rb)
|
307
|
-
for the default behavior.
|
197
|
+
See [app/views](/app/views) for the default behavior.
|
308
198
|
|
309
|
-
|
199
|
+
To override a view, create your own copy of it:
|
310
200
|
|
311
|
-
```ruby
|
312
|
-
Clearance.configure do |config|
|
313
|
-
config.password_strategy = Clearance::PasswordStrategies::SHA1
|
314
|
-
end
|
315
201
|
```
|
316
|
-
|
317
|
-
|
318
|
-
|
319
|
-
|
320
|
-
|
321
|
-
|
322
|
-
|
323
|
-
|
202
|
+
app/views/clearance_mailer/change_password.html.erb
|
203
|
+
app/views/passwords/create.html.erb
|
204
|
+
app/views/passwords/edit.html.erb
|
205
|
+
app/views/passwords/new.html.erb
|
206
|
+
app/views/sessions/_form.html.erb
|
207
|
+
app/views/sessions/new.html.erb
|
208
|
+
app/views/users/_form.html.erb
|
209
|
+
app/views/users/new.html.erb
|
324
210
|
```
|
325
211
|
|
326
|
-
|
327
|
-
|
328
|
-
Switching password strategies may cause your existing users to not be able to sign in.
|
212
|
+
You can use the Clearance views generator to copy the default views to your
|
213
|
+
application for modification.
|
329
214
|
|
330
|
-
|
331
|
-
|
332
|
-
|
215
|
+
```shell
|
216
|
+
$ rails generate clearance:views
|
217
|
+
```
|
333
218
|
|
334
|
-
|
335
|
-
switch to BCrypt transparently, use
|
336
|
-
[Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
|
219
|
+
### Layouts
|
337
220
|
|
338
|
-
|
339
|
-
|
221
|
+
By default, Clearance uses your application's default layout. If you would like
|
222
|
+
to change the layout that Clearance uses when rendering its views, simply
|
223
|
+
specify the layout in an initializer.
|
340
224
|
|
341
225
|
```ruby
|
342
|
-
|
343
|
-
|
344
|
-
|
345
|
-
end
|
346
|
-
end
|
226
|
+
Clearance::PasswordsController.layout 'my_passwords_layout'
|
227
|
+
Clearance::SessionsController.layout 'my_sessions_layout'
|
228
|
+
Clearance::UsersController.layout 'my_admin_layout'
|
347
229
|
```
|
348
230
|
|
349
|
-
|
350
|
-
In your `authenticated?` method, encrypt the password with your desired
|
351
|
-
strategy, and then compare it to the `encrypted_password` that is provided by
|
352
|
-
Clearance.
|
231
|
+
### Translations
|
353
232
|
|
354
|
-
|
355
|
-
|
356
|
-
|
357
|
-
encrypted_password == encrypt(password)
|
358
|
-
end
|
359
|
-
|
360
|
-
def password=(new_password)
|
361
|
-
end
|
233
|
+
All flash messages and email subject lines are stored in [i18n translations]
|
234
|
+
(http://guides.rubyonrails.org/i18n.html). Override them like any other
|
235
|
+
translation.
|
362
236
|
|
363
|
-
|
237
|
+
See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
|
238
|
+
default behavior.
|
364
239
|
|
365
|
-
|
366
|
-
# your encryption strategy
|
367
|
-
end
|
368
|
-
end
|
240
|
+
### User Model
|
369
241
|
|
370
|
-
|
371
|
-
|
372
|
-
end
|
373
|
-
```
|
242
|
+
See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
|
243
|
+
You can override those methods as needed.
|
374
244
|
|
375
|
-
Deliver
|
376
|
-
------------------------------------------------
|
245
|
+
### Deliver Email in Background Job
|
377
246
|
|
378
|
-
Clearance has
|
247
|
+
Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
|
248
|
+
1.6 or greater, Clearance will use ActiveJob's `deliver_later` method to
|
249
|
+
automatically take advantage of your configured queue.
|
379
250
|
|
380
|
-
|
381
|
-
|
382
|
-
`
|
383
|
-
`deliver_email` method:
|
251
|
+
If you are using an earlier version of Rails, you can override the
|
252
|
+
`Clearance::Passwords` controller and define the behavior you need in the
|
253
|
+
`deliver_email` method.
|
384
254
|
|
385
255
|
```ruby
|
386
256
|
class PasswordsController < Clearance::PasswordsController
|
@@ -390,14 +260,13 @@ class PasswordsController < Clearance::PasswordsController
|
|
390
260
|
end
|
391
261
|
```
|
392
262
|
|
393
|
-
|
394
|
-
|
395
|
-
```ruby
|
396
|
-
resources :passwords, only: [:create]
|
397
|
-
```
|
263
|
+
## Extending Sign In
|
398
264
|
|
399
|
-
|
400
|
-
|
265
|
+
By default, Clearance will sign in any user with valid credentials. If you need
|
266
|
+
to support additional checks during the sign in process then you can use the
|
267
|
+
SignInGuard stack. For example, using the SignInGuard stack, you could prevent
|
268
|
+
suspended users from signing in, or require that users confirm their email
|
269
|
+
address before accessing the site.
|
401
270
|
|
402
271
|
`SignInGuard`s offer fine-grained control over the process of
|
403
272
|
signing in a user. Each guard is run in order and hands the session off to
|
@@ -441,39 +310,52 @@ class EmailConfirmationGuard < Clearance::SignInGuard
|
|
441
310
|
end
|
442
311
|
```
|
443
312
|
|
444
|
-
|
445
|
-
|
313
|
+
## Testing
|
314
|
+
|
315
|
+
### Fast Feature Specs
|
316
|
+
|
317
|
+
Clearance includes middleware that avoids wasting time spent visiting, loading,
|
318
|
+
and submitting the sign in form. It instead signs in the designated user
|
319
|
+
directly. The speed increase can be [substantial][backdoor].
|
446
320
|
|
447
|
-
|
448
|
-
integration with your Rails app over time.
|
321
|
+
[backdoor]: http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door
|
449
322
|
|
450
|
-
|
323
|
+
Enable the Middleware in Test:
|
451
324
|
|
452
325
|
```ruby
|
453
|
-
|
454
|
-
|
455
|
-
|
326
|
+
# config/environments/test.rb
|
327
|
+
MyRailsApp::Application.configure do
|
328
|
+
# ...
|
329
|
+
config.middleware.use Clearance::BackDoor
|
330
|
+
# ...
|
331
|
+
end
|
456
332
|
```
|
457
333
|
|
458
|
-
|
334
|
+
Usage:
|
459
335
|
|
460
|
-
|
336
|
+
```ruby
|
337
|
+
visit root_path(as: user)
|
338
|
+
```
|
461
339
|
|
462
|
-
|
340
|
+
### Ready Made Feature Specs
|
463
341
|
|
464
|
-
|
342
|
+
If you're using RSpec, you can generate feature specs to help prevent
|
343
|
+
regressions in Clearance's integration with your Rails app over time. These
|
344
|
+
feature specs, will also require `factory_girl_rails`.
|
465
345
|
|
466
|
-
|
346
|
+
To Generate the clearance specs, run:
|
467
347
|
|
468
|
-
|
348
|
+
```shell
|
349
|
+
$ rails generate clearance:specs
|
350
|
+
```
|
469
351
|
|
470
|
-
|
471
|
-
---------------------------------------------
|
352
|
+
### Controller Test Helpers
|
472
353
|
|
473
|
-
To test controller actions that are protected by `
|
474
|
-
require Clearance's test helpers
|
354
|
+
To test controller actions that are protected by `before_action :require_login`,
|
355
|
+
require Clearance's test helpers in your test suite.
|
475
356
|
|
476
|
-
For `rspec`, add
|
357
|
+
For `rspec`, add the following line to your `spec/rails_helper.rb` or
|
358
|
+
`spec/spec_helper` if `rails_helper` does not exist:
|
477
359
|
|
478
360
|
```ruby
|
479
361
|
require 'clearance/rspec'
|
@@ -488,81 +370,54 @@ require 'clearance/test_unit'
|
|
488
370
|
This will make `Clearance::Controller` methods work in your controllers
|
489
371
|
during functional tests and provide access to helper methods like:
|
490
372
|
|
491
|
-
sign_in
|
492
|
-
sign_in_as(user)
|
493
|
-
sign_out
|
494
|
-
|
495
|
-
And matchers like:
|
496
|
-
|
497
|
-
deny_access
|
498
|
-
|
499
|
-
Example:
|
500
|
-
|
501
373
|
```ruby
|
502
|
-
|
503
|
-
|
504
|
-
|
505
|
-
end
|
506
|
-
|
507
|
-
it { should deny_access }
|
508
|
-
end
|
509
|
-
|
510
|
-
context 'a user' do
|
511
|
-
before do
|
512
|
-
sign_in
|
513
|
-
get :show
|
514
|
-
end
|
515
|
-
|
516
|
-
it { should respond_with(:success) }
|
517
|
-
end
|
374
|
+
sign_in
|
375
|
+
sign_in_as(user)
|
376
|
+
sign_out
|
518
377
|
```
|
519
378
|
|
520
|
-
|
379
|
+
### View and Helper Spec Helpers
|
380
|
+
|
381
|
+
Does the view or helper you're testing reference `signed_in?`, `signed_out?` or
|
382
|
+
`current_user`? If you `require 'clearance/rspec'`, you will have the following
|
383
|
+
helpers available in your view specs:
|
521
384
|
|
522
385
|
```ruby
|
523
|
-
|
524
|
-
|
525
|
-
it { should deny_access(redirect: sign_in_url) }
|
386
|
+
sign_in
|
387
|
+
sign_in_as(user)
|
526
388
|
```
|
527
389
|
|
528
|
-
|
529
|
-
|
390
|
+
These will make the clearance view helpers work as expected by signing in either
|
391
|
+
a new instance of your user model (`sign_in`) or the object you pass to
|
392
|
+
`sign_in_as`. If you do not call one of these sign in helpers or otherwise set
|
393
|
+
`current_user` in your view specs, your view will behave as if there is no
|
394
|
+
current user: `signed_in?` will be false and `signed_out?` will be true.
|
530
395
|
|
531
|
-
|
532
|
-
and submitting the sign in form. It instead signs in the designated
|
533
|
-
user directly. The speed increase can be
|
534
|
-
[substantial](http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door).
|
396
|
+
## Contributing
|
535
397
|
|
536
|
-
|
398
|
+
Please see [CONTRIBUTING.md].
|
399
|
+
Thank you, [contributors]!
|
537
400
|
|
538
|
-
|
539
|
-
|
540
|
-
MyRailsApp::Application.configure do
|
541
|
-
# ...
|
542
|
-
config.middleware.use Clearance::BackDoor
|
543
|
-
# ...
|
544
|
-
end
|
545
|
-
```
|
401
|
+
[CONTRIBUTING.md]: /CONTRIBUTING.md
|
402
|
+
[contributors]: https://github.com/thoughtbot/clearance/graphs/contributors
|
546
403
|
|
547
|
-
|
404
|
+
## License
|
548
405
|
|
549
|
-
|
550
|
-
|
551
|
-
```
|
406
|
+
Clearance is copyright © 2009 thoughtbot. It is free software, and may be
|
407
|
+
redistributed under the terms specified in the [`LICENSE`] file.
|
552
408
|
|
553
|
-
|
554
|
-
-------
|
409
|
+
[`LICENSE`]: /LICENSE
|
555
410
|
|
556
|
-
|
411
|
+
## About thoughtbot
|
557
412
|
|
558
|
-
|
559
|
-
and [contributors](https://github.com/thoughtbot/clearance/contributors) like
|
560
|
-
you. Thank you!
|
413
|
+
![thoughtbot](https://thoughtbot.com/logo.png)
|
561
414
|
|
562
|
-
|
563
|
-
|
415
|
+
Clearance is maintained and funded by thoughtbot, inc.
|
416
|
+
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
|
564
417
|
|
565
|
-
|
566
|
-
|
418
|
+
We love open source software!
|
419
|
+
See [our other projects][community] or
|
420
|
+
[hire us][hire] to design, develop, and grow your product.
|
567
421
|
|
568
|
-
|
422
|
+
[community]: https://thoughtbot.com/community?utm_source=github
|
423
|
+
[hire]: https://thoughtbot.com/hire-us?utm_source=github
|