clearance 1.8.0 → 1.16.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 +3 -0
- data/.travis.yml +25 -6
- data/.yardopts +6 -0
- data/Appraisals +15 -4
- data/CONTRIBUTING.md +4 -1
- data/Gemfile +5 -3
- data/Gemfile.lock +102 -96
- data/NEWS.md +742 -311
- data/README.md +217 -339
- data/app/controllers/clearance/passwords_controller.rb +35 -21
- 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} +4 -2
- data/gemfiles/{rails4.0.gemfile → rails40.gemfile} +6 -3
- data/gemfiles/{rails4.1.gemfile → rails41.gemfile} +6 -3
- data/gemfiles/{rails4.2.gemfile → rails42.gemfile} +6 -3
- data/gemfiles/rails50.gemfile +21 -0
- data/lib/clearance/authentication.rb +61 -2
- data/lib/clearance/authorization.rb +47 -4
- data/lib/clearance/back_door.rb +29 -6
- data/lib/clearance/configuration.rb +152 -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 +16 -21
- 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 +36 -2
- 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 +182 -4
- data/lib/clearance/version.rb +1 -1
- data/lib/clearance.rb +2 -0
- data/lib/generators/clearance/install/install_generator.rb +24 -5
- data/lib/generators/clearance/install/templates/clearance.rb +1 -0
- 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/install/templates/user.rb.erb +3 -0
- 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/app/models/rails5/user.rb +5 -0
- 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/back_door_spec.rb +25 -6
- data/spec/clearance/controller_spec.rb +11 -0
- data/spec/clearance/rack_session_spec.rb +5 -5
- data/spec/clearance/session_spec.rb +2 -15
- 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 +94 -86
- 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 +17 -16
- 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 +29 -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/requests/csrf_rotation_spec.rb +33 -0
- data/spec/spec_helper.rb +11 -2
- data/spec/support/generator_spec_helpers.rb +13 -1
- 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 +22 -9
- data/lib/generators/clearance/install/templates/user.rb +0 -3
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,100 +16,68 @@ 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
|
-
```
|
31
|
-
gem
|
25
|
+
```sh
|
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
|
|
62
49
|
```ruby
|
63
50
|
Clearance.configure do |config|
|
64
51
|
config.allow_sign_up = true
|
65
|
-
config.cookie_domain =
|
52
|
+
config.cookie_domain = ".example.com"
|
66
53
|
config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
|
67
|
-
config.cookie_name =
|
68
|
-
config.cookie_path =
|
54
|
+
config.cookie_name = "remember_token"
|
55
|
+
config.cookie_path = "/"
|
69
56
|
config.routes = true
|
70
57
|
config.httponly = false
|
71
|
-
config.mailer_sender =
|
58
|
+
config.mailer_sender = "reply@example.com"
|
72
59
|
config.password_strategy = Clearance::PasswordStrategies::BCrypt
|
73
|
-
config.redirect_url =
|
60
|
+
config.redirect_url = "/"
|
61
|
+
config.rotate_csrf_on_sign_in = false
|
74
62
|
config.secure_cookie = false
|
75
63
|
config.sign_in_guards = []
|
76
64
|
config.user_model = User
|
77
65
|
end
|
78
66
|
```
|
79
67
|
|
80
|
-
|
81
|
-
|
68
|
+
The install generator will set `rotate_csrf_on_sign_in` to `true`, so new
|
69
|
+
installations will get this behavior from the start. This helps avoid session
|
70
|
+
fixation attacks, and will become the default in Clearance 2.0.
|
82
71
|
|
83
|
-
Use
|
84
|
-
helpers. For example:
|
72
|
+
## Use
|
85
73
|
|
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
|
-
```
|
74
|
+
### Access Control
|
93
75
|
|
94
|
-
|
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:
|
76
|
+
Use the `require_login` filter to control access to controller actions.
|
110
77
|
|
111
78
|
```ruby
|
112
79
|
class ArticlesController < ApplicationController
|
113
|
-
|
80
|
+
before_action :require_login
|
114
81
|
|
115
82
|
def index
|
116
83
|
current_user.articles
|
@@ -118,24 +85,52 @@ class ArticlesController < ApplicationController
|
|
118
85
|
end
|
119
86
|
```
|
120
87
|
|
121
|
-
|
88
|
+
Clearance also provides routing constraints that can be used to control access
|
89
|
+
at the routing layer:
|
122
90
|
|
123
91
|
```ruby
|
124
92
|
Blog::Application.routes.draw do
|
125
93
|
constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
|
126
|
-
root to:
|
94
|
+
root to: "admin/dashboards#show", as: :admin_root
|
127
95
|
end
|
128
96
|
|
129
97
|
constraints Clearance::Constraints::SignedIn.new do
|
130
|
-
root to:
|
98
|
+
root to: "dashboards#show", as: :signed_in_root
|
131
99
|
end
|
132
100
|
|
133
101
|
constraints Clearance::Constraints::SignedOut.new do
|
134
|
-
root to:
|
102
|
+
root to: "marketing#index"
|
135
103
|
end
|
136
104
|
end
|
137
105
|
```
|
138
106
|
|
107
|
+
### Helper Methods
|
108
|
+
|
109
|
+
Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
|
110
|
+
helpers. For example:
|
111
|
+
|
112
|
+
```erb
|
113
|
+
<% if signed_in? %>
|
114
|
+
<%= current_user.email %>
|
115
|
+
<%= button_to "Sign out", sign_out_path, method: :delete %>
|
116
|
+
<% else %>
|
117
|
+
<%= link_to "Sign in", sign_in_path %>
|
118
|
+
<% end %>
|
119
|
+
```
|
120
|
+
|
121
|
+
### Password Resets
|
122
|
+
|
123
|
+
When a user resets their password, Clearance delivers them an email. You
|
124
|
+
should change the `mailer_sender` default, used in the email's "from" header:
|
125
|
+
|
126
|
+
```ruby
|
127
|
+
Clearance.configure do |config|
|
128
|
+
config.mailer_sender = "reply@example.com"
|
129
|
+
end
|
130
|
+
```
|
131
|
+
|
132
|
+
### Integrating with Rack Applications
|
133
|
+
|
139
134
|
Clearance adds its session to the Rack environment hash so middleware and other
|
140
135
|
Rack applications can interact with it:
|
141
136
|
|
@@ -155,28 +150,28 @@ class Bubblegum::Middleware
|
|
155
150
|
end
|
156
151
|
```
|
157
152
|
|
158
|
-
Overriding
|
159
|
-
|
153
|
+
## Overriding Clearance
|
154
|
+
|
155
|
+
### Routes
|
160
156
|
|
161
157
|
See [config/routes.rb](/config/routes.rb) for the default set of routes.
|
162
158
|
|
163
|
-
|
164
|
-
|
165
|
-
|
159
|
+
As of Clearance 1.5 it is recommended that you disable Clearance routes and take
|
160
|
+
full control over routing and URL design. This ensures that your app's URL design
|
161
|
+
won't be affected if the gem's routes and URL design are changed.
|
166
162
|
|
167
163
|
To disable the routes, set `config.routes = false`. You can optionally run
|
168
164
|
`rails generate clearance:routes` to dump a copy of the default routes into your
|
169
165
|
application for modification.
|
170
166
|
|
171
|
-
|
172
|
-
|
173
|
-
Overriding controllers
|
174
|
-
----------------------
|
167
|
+
### Controllers
|
175
168
|
|
176
169
|
See [app/controllers/clearance](/app/controllers/clearance) for the default
|
177
|
-
behavior.
|
170
|
+
behavior. Many protected methods were extracted in these controllers in an
|
171
|
+
attempt to make overrides and hooks simpler.
|
178
172
|
|
179
|
-
To override a Clearance controller, subclass it
|
173
|
+
To override a Clearance controller, subclass it and update the routes to
|
174
|
+
point to your new controller (see the "Routes" section).
|
180
175
|
|
181
176
|
```ruby
|
182
177
|
class PasswordsController < Clearance::PasswordsController
|
@@ -184,203 +179,87 @@ class SessionsController < Clearance::SessionsController
|
|
184
179
|
class UsersController < Clearance::UsersController
|
185
180
|
```
|
186
181
|
|
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.
|
182
|
+
### Redirects
|
246
183
|
|
247
|
-
|
248
|
-
|
184
|
+
All of these controller methods redirect to
|
185
|
+
`Clearance.configuration.redirect_url` (which is `/` by default):
|
249
186
|
|
250
|
-
|
251
|
-
|
252
|
-
|
253
|
-
|
254
|
-
|
255
|
-
|
256
|
-
Clearance::SessionsController.layout 'my_sessions_layout'
|
257
|
-
Clearance::UsersController.layout 'my_admin_layout'
|
187
|
+
```
|
188
|
+
passwords#url_after_update
|
189
|
+
sessions#url_after_create
|
190
|
+
sessions#url_for_signed_in_users
|
191
|
+
users#url_after_create
|
192
|
+
application#url_after_denied_access_when_signed_in
|
258
193
|
```
|
259
194
|
|
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?
|
195
|
+
To override them all at once, change the global configuration of `redirect_url`.
|
196
|
+
To change individual URLs, override the appropriate method.
|
299
197
|
|
300
|
-
|
301
|
-
|
198
|
+
`application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
|
199
|
+
Override this method to change this.
|
302
200
|
|
303
|
-
|
201
|
+
### Views
|
304
202
|
|
305
|
-
See
|
306
|
-
[lib/clearance/password_strategies/bcrypt.rb](/lib/clearance/password_strategies/bcrypt.rb)
|
307
|
-
for the default behavior.
|
203
|
+
See [app/views](/app/views) for the default behavior.
|
308
204
|
|
309
|
-
|
205
|
+
To override a view, create your own copy of it:
|
310
206
|
|
311
|
-
```ruby
|
312
|
-
Clearance.configure do |config|
|
313
|
-
config.password_strategy = Clearance::PasswordStrategies::SHA1
|
314
|
-
end
|
315
207
|
```
|
316
|
-
|
317
|
-
|
318
|
-
|
319
|
-
|
320
|
-
|
321
|
-
|
322
|
-
|
323
|
-
|
208
|
+
app/views/clearance_mailer/change_password.html.erb
|
209
|
+
app/views/passwords/create.html.erb
|
210
|
+
app/views/passwords/edit.html.erb
|
211
|
+
app/views/passwords/new.html.erb
|
212
|
+
app/views/sessions/_form.html.erb
|
213
|
+
app/views/sessions/new.html.erb
|
214
|
+
app/views/users/_form.html.erb
|
215
|
+
app/views/users/new.html.erb
|
324
216
|
```
|
325
217
|
|
326
|
-
|
327
|
-
|
328
|
-
Switching password strategies may cause your existing users to not be able to sign in.
|
218
|
+
You can use the Clearance views generator to copy the default views to your
|
219
|
+
application for modification.
|
329
220
|
|
330
|
-
|
331
|
-
|
332
|
-
|
221
|
+
```shell
|
222
|
+
$ rails generate clearance:views
|
223
|
+
```
|
333
224
|
|
334
|
-
|
335
|
-
switch to BCrypt transparently, use
|
336
|
-
[Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
|
225
|
+
### Layouts
|
337
226
|
|
338
|
-
|
339
|
-
|
227
|
+
By default, Clearance uses your application's default layout. If you would like
|
228
|
+
to change the layout that Clearance uses when rendering its views, simply
|
229
|
+
specify the layout in an initializer.
|
340
230
|
|
341
231
|
```ruby
|
342
|
-
|
343
|
-
|
344
|
-
|
345
|
-
end
|
346
|
-
end
|
232
|
+
Clearance::PasswordsController.layout "my_passwords_layout"
|
233
|
+
Clearance::SessionsController.layout "my_sessions_layout"
|
234
|
+
Clearance::UsersController.layout "my_admin_layout"
|
347
235
|
```
|
348
236
|
|
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.
|
237
|
+
### Translations
|
353
238
|
|
354
|
-
|
355
|
-
|
356
|
-
|
357
|
-
encrypted_password == encrypt(password)
|
358
|
-
end
|
239
|
+
All flash messages and email subject lines are stored in [i18n translations]
|
240
|
+
(http://guides.rubyonrails.org/i18n.html). Override them like any other
|
241
|
+
translation.
|
359
242
|
|
360
|
-
|
361
|
-
|
243
|
+
See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
|
244
|
+
default behavior.
|
362
245
|
|
363
|
-
|
246
|
+
You can also install [clearance-i18n](https://github.com/thoughtbot/clearance-i18n)
|
247
|
+
for access to additional, user-contributed translations.
|
364
248
|
|
365
|
-
|
366
|
-
# your encryption strategy
|
367
|
-
end
|
368
|
-
end
|
249
|
+
### User Model
|
369
250
|
|
370
|
-
|
371
|
-
|
372
|
-
end
|
373
|
-
```
|
251
|
+
See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
|
252
|
+
You can override those methods as needed.
|
374
253
|
|
375
|
-
Deliver
|
376
|
-
------------------------------------------------
|
254
|
+
### Deliver Email in Background Job
|
377
255
|
|
378
|
-
Clearance has
|
256
|
+
Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
|
257
|
+
1.6 or greater, Clearance will use ActiveJob's `deliver_later` method to
|
258
|
+
automatically take advantage of your configured queue.
|
379
259
|
|
380
|
-
|
381
|
-
|
382
|
-
`
|
383
|
-
`deliver_email` method:
|
260
|
+
If you are using an earlier version of Rails, you can override the
|
261
|
+
`Clearance::Passwords` controller and define the behavior you need in the
|
262
|
+
`deliver_email` method.
|
384
263
|
|
385
264
|
```ruby
|
386
265
|
class PasswordsController < Clearance::PasswordsController
|
@@ -390,14 +269,13 @@ class PasswordsController < Clearance::PasswordsController
|
|
390
269
|
end
|
391
270
|
```
|
392
271
|
|
393
|
-
|
394
|
-
|
395
|
-
```ruby
|
396
|
-
resources :passwords, only: [:create]
|
397
|
-
```
|
272
|
+
## Extending Sign In
|
398
273
|
|
399
|
-
|
400
|
-
|
274
|
+
By default, Clearance will sign in any user with valid credentials. If you need
|
275
|
+
to support additional checks during the sign in process then you can use the
|
276
|
+
SignInGuard stack. For example, using the SignInGuard stack, you could prevent
|
277
|
+
suspended users from signing in, or require that users confirm their email
|
278
|
+
address before accessing the site.
|
401
279
|
|
402
280
|
`SignInGuard`s offer fine-grained control over the process of
|
403
281
|
signing in a user. Each guard is run in order and hands the session off to
|
@@ -441,128 +319,128 @@ class EmailConfirmationGuard < Clearance::SignInGuard
|
|
441
319
|
end
|
442
320
|
```
|
443
321
|
|
444
|
-
|
445
|
-
|
322
|
+
## Testing
|
323
|
+
|
324
|
+
### Fast Feature Specs
|
325
|
+
|
326
|
+
Clearance includes middleware that avoids wasting time spent visiting, loading,
|
327
|
+
and submitting the sign in form. It instead signs in the designated user
|
328
|
+
directly. The speed increase can be [substantial][backdoor].
|
329
|
+
|
330
|
+
[backdoor]: http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door
|
446
331
|
|
447
|
-
|
448
|
-
|
332
|
+
Enable the Middleware in Test:
|
333
|
+
|
334
|
+
```ruby
|
335
|
+
# config/environments/test.rb
|
336
|
+
MyRailsApp::Application.configure do
|
337
|
+
# ...
|
338
|
+
config.middleware.use Clearance::BackDoor
|
339
|
+
# ...
|
340
|
+
end
|
341
|
+
```
|
449
342
|
|
450
|
-
|
343
|
+
Usage:
|
451
344
|
|
452
345
|
```ruby
|
453
|
-
|
454
|
-
gem 'factory_girl_rails', '~> 4.2'
|
455
|
-
gem 'rspec-rails', '~> 2.13'
|
346
|
+
visit root_path(as: user)
|
456
347
|
```
|
457
348
|
|
458
|
-
|
349
|
+
Additionally, if `User#to_param` is overridden, you can pass a block in
|
350
|
+
order to override the default behavior:
|
459
351
|
|
460
|
-
|
352
|
+
```ruby
|
353
|
+
# config/environments/test.rb
|
354
|
+
MyRailsApp::Application.configure do
|
355
|
+
# ...
|
356
|
+
config.middleware.use Clearance::BackDoor do |username|
|
357
|
+
Clearance.configuration.user_model.find_by(username: username)
|
358
|
+
end
|
359
|
+
# ...
|
360
|
+
end
|
361
|
+
```
|
461
362
|
|
462
|
-
|
363
|
+
### Ready Made Feature Specs
|
463
364
|
|
464
|
-
|
365
|
+
If you're using RSpec, you can generate feature specs to help prevent
|
366
|
+
regressions in Clearance's integration with your Rails app over time. These
|
367
|
+
feature specs, will also require `factory_girl_rails`.
|
465
368
|
|
466
|
-
|
369
|
+
To Generate the clearance specs, run:
|
467
370
|
|
468
|
-
|
371
|
+
```shell
|
372
|
+
$ rails generate clearance:specs
|
373
|
+
```
|
469
374
|
|
470
|
-
|
471
|
-
---------------------------------------------
|
375
|
+
### Controller Test Helpers
|
472
376
|
|
473
|
-
To test controller actions that are protected by `
|
474
|
-
require Clearance's test helpers
|
377
|
+
To test controller actions that are protected by `before_action :require_login`,
|
378
|
+
require Clearance's test helpers in your test suite.
|
475
379
|
|
476
|
-
For `rspec`, add
|
380
|
+
For `rspec`, add the following line to your `spec/rails_helper.rb` or
|
381
|
+
`spec/spec_helper` if `rails_helper` does not exist:
|
477
382
|
|
478
383
|
```ruby
|
479
|
-
require
|
384
|
+
require "clearance/rspec"
|
480
385
|
```
|
481
386
|
|
482
387
|
For `test-unit`, add this line to your `test/test_helper.rb`:
|
483
388
|
|
484
389
|
```ruby
|
485
|
-
require
|
390
|
+
require "clearance/test_unit"
|
486
391
|
```
|
487
392
|
|
488
393
|
This will make `Clearance::Controller` methods work in your controllers
|
489
394
|
during functional tests and provide access to helper methods like:
|
490
395
|
|
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
396
|
```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
|
397
|
+
sign_in
|
398
|
+
sign_in_as(user)
|
399
|
+
sign_out
|
518
400
|
```
|
519
401
|
|
520
|
-
|
402
|
+
### View and Helper Spec Helpers
|
403
|
+
|
404
|
+
Does the view or helper you're testing reference `signed_in?`, `signed_out?` or
|
405
|
+
`current_user`? If you `require 'clearance/rspec'`, you will have the following
|
406
|
+
helpers available in your view specs:
|
521
407
|
|
522
408
|
```ruby
|
523
|
-
|
524
|
-
|
525
|
-
it { should deny_access(redirect: sign_in_url) }
|
409
|
+
sign_in
|
410
|
+
sign_in_as(user)
|
526
411
|
```
|
527
412
|
|
528
|
-
|
529
|
-
|
413
|
+
These will make the clearance view helpers work as expected by signing in either
|
414
|
+
a new instance of your user model (`sign_in`) or the object you pass to
|
415
|
+
`sign_in_as`. If you do not call one of these sign in helpers or otherwise set
|
416
|
+
`current_user` in your view specs, your view will behave as if there is no
|
417
|
+
current user: `signed_in?` will be false and `signed_out?` will be true.
|
530
418
|
|
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).
|
419
|
+
## Contributing
|
535
420
|
|
536
|
-
|
421
|
+
Please see [CONTRIBUTING.md].
|
422
|
+
Thank you, [contributors]!
|
537
423
|
|
538
|
-
|
539
|
-
|
540
|
-
MyRailsApp::Application.configure do
|
541
|
-
# ...
|
542
|
-
config.middleware.use Clearance::BackDoor
|
543
|
-
# ...
|
544
|
-
end
|
545
|
-
```
|
424
|
+
[CONTRIBUTING.md]: /CONTRIBUTING.md
|
425
|
+
[contributors]: https://github.com/thoughtbot/clearance/graphs/contributors
|
546
426
|
|
547
|
-
|
427
|
+
## License
|
548
428
|
|
549
|
-
|
550
|
-
|
551
|
-
```
|
429
|
+
Clearance is copyright © 2009 thoughtbot. It is free software, and may be
|
430
|
+
redistributed under the terms specified in the [`LICENSE`] file.
|
552
431
|
|
553
|
-
|
554
|
-
-------
|
432
|
+
[`LICENSE`]: /LICENSE
|
555
433
|
|
556
|
-
|
434
|
+
## About thoughtbot
|
557
435
|
|
558
|
-
|
559
|
-
and [contributors](https://github.com/thoughtbot/clearance/contributors) like
|
560
|
-
you. Thank you!
|
436
|
+
![thoughtbot](https://thoughtbot.com/logo.png)
|
561
437
|
|
562
|
-
|
563
|
-
|
438
|
+
Clearance is maintained and funded by thoughtbot, inc.
|
439
|
+
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
|
564
440
|
|
565
|
-
|
566
|
-
|
441
|
+
We love open source software!
|
442
|
+
See [our other projects][community] or
|
443
|
+
[hire us][hire] to design, develop, and grow your product.
|
567
444
|
|
568
|
-
|
445
|
+
[community]: https://thoughtbot.com/community?utm_source=github
|
446
|
+
[hire]: https://thoughtbot.com/hire-us?utm_source=github
|