clearance 1.8.0 → 1.16.0

data/README.md

@@ -1,14 +1,13 @@
-Clearance
-=========
+# Clearance
 
 [![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.svg)](http://travis-ci.org/thoughtbot/clearance?branch=master)
 [![Code Climate](https://codeclimate.com/github/thoughtbot/clearance.svg)](https://codeclimate.com/github/thoughtbot/clearance)
+[![Documentation Quality](https://inch-ci.org/github/thoughtbot/clearance.svg?branch=master)](https://inch-ci.org/github/thoughtbot/clearance)
 
 Rails authentication with email & password.
 
-Clearance was extracted out of [Airbrake](http://airbrake.io/). It is intended
-to be small, simple, and well-tested. It is intended to be easy to override
-defaults.
+Clearance is intended to be small, simple, and well-tested. It has opinionated
+defaults but is intended to be easy to override.
 
 Please use [GitHub Issues] to report bugs. If you have a question about the
 library, please use the `clearance` tag on [Stack Overflow]. This tag is
@@ -17,100 +16,68 @@ monitored by contributors.
 [GitHub Issues]: https://github.com/thoughtbot/clearance/issues
 [Stack Overflow]: http://stackoverflow.com/questions/tagged/clearance
 
-Read [CONTRIBUTING.md](/CONTRIBUTING.md) to contribute.
-
-Install
--------
+## Getting Started
 
 Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
-It works with Rails 4 and Ruby 2.
 
-Include the gem in your Gemfile:
+You can add it to your Gemfile with:
 
-```ruby
-gem 'clearance'
+```sh
+gem "clearance"
 ```
 
-Bundle:
-
-    bundle install
-
-Make sure the development database exists. Then, run the generator:
-
-    rails generate clearance:install
+Run the bundle command to install it.
 
-The generator:
+After you install Clearance, you need to run the generator:
 
-* inserts `Clearance::User` into your `User` model
-* inserts `Clearance::Controller` into your `ApplicationController`
-* creates a migration that either creates a users table or adds only missing
-  columns
-
-Then, follow the instructions output from the generator.
+```sh
+$ rails generate clearance:install
+```
 
-Use Clearance [0.8.8](https://github.com/thoughtbot/clearance/tree/v0.8.8) for
-Rails 2 apps.
+The Clearance install generator:
 
-Use Clearance [0.16.3](http://rubygems.org/gems/clearance/versions/0.16.3) for
-Ruby 1.8.7 apps.
+* Inserts `Clearance::User` into your `User` model
+* Inserts `Clearance::Controller` into your `ApplicationController`
+* Creates an initializer file to allow further configuration.
+* Creates a migration file that either create a users table or adds any necessary
+  columns to the existing table.
 
-Configure
----------
+## Configure
 
 Override any of these defaults in `config/initializers/clearance.rb`:
 
 ```ruby
 Clearance.configure do |config|
   config.allow_sign_up = true
-  config.cookie_domain = '.example.com'
+  config.cookie_domain = ".example.com"
   config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
-  config.cookie_name = 'remember_token'
-  config.cookie_path = '/'
+  config.cookie_name = "remember_token"
+  config.cookie_path = "/"
   config.routes = true
   config.httponly = false
-  config.mailer_sender = 'reply@example.com'
+  config.mailer_sender = "reply@example.com"
   config.password_strategy = Clearance::PasswordStrategies::BCrypt
-  config.redirect_url = '/'
+  config.redirect_url = "/"
+  config.rotate_csrf_on_sign_in = false
   config.secure_cookie = false
   config.sign_in_guards = []
   config.user_model = User
 end
 ```
 
-Use
----
+The install generator will set `rotate_csrf_on_sign_in` to `true`, so new
+installations will get this behavior from the start. This helps avoid session
+fixation attacks, and will become the default in Clearance 2.0.
 
-Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
-helpers. For example:
+## Use
 
-```haml
-- if signed_in?
-  = current_user.email
-  = button_to 'Sign out', sign_out_path, method: :delete
-- else
-  = link_to 'Sign in', sign_in_path
-```
+### Access Control
 
-To authenticate a user elsewhere than `sessions/new` (like in an API):
-
-```ruby
-User.authenticate 'email@example.com', 'password'
-```
-
-When a user resets their password, Clearance delivers them an email. So, you
-should change the `mailer_sender` default, used in the email's "from" header:
-
-```ruby
-Clearance.configure do |config|
-  config.mailer_sender = 'reply@example.com'
-end
-```
-
-Use `require_login` to control access in controllers:
+Use the `require_login` filter to control access to controller actions.
 
 ```ruby
 class ArticlesController < ApplicationController
-  before_filter :require_login
+  before_action :require_login
 
   def index
     current_user.articles
@@ -118,24 +85,52 @@ class ArticlesController < ApplicationController
 end
 ```
 
-Or, you can authorize users in `config/routes.rb`:
+Clearance also provides routing constraints that can be used to control access
+at the routing layer:
 
 ```ruby
 Blog::Application.routes.draw do
   constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
-    root to: 'admin/dashboards#show', as: :admin_root
+    root to: "admin/dashboards#show", as: :admin_root
   end
 
   constraints Clearance::Constraints::SignedIn.new do
-    root to: 'dashboards#show', as: :signed_in_root
+    root to: "dashboards#show", as: :signed_in_root
   end
 
   constraints Clearance::Constraints::SignedOut.new do
-    root to: 'marketing#index'
+    root to: "marketing#index"
   end
 end
 ```
 
+### Helper Methods
+
+Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
+helpers. For example:
+
+```erb
+<% if signed_in? %>
+  <%= current_user.email %>
+  <%= button_to "Sign out", sign_out_path, method: :delete %>
+<% else %>
+  <%= link_to "Sign in", sign_in_path %>
+<% end %>
+```
+
+### Password Resets
+
+When a user resets their password, Clearance delivers them an email. You
+should change the `mailer_sender` default, used in the email's "from" header:
+
+```ruby
+Clearance.configure do |config|
+  config.mailer_sender = "reply@example.com"
+end
+```
+
+### Integrating with Rack Applications
+
 Clearance adds its session to the Rack environment hash so middleware and other
 Rack applications can interact with it:
 
@@ -155,28 +150,28 @@ class Bubblegum::Middleware
 end
 ```
 
-Overriding routes
------------------
+## Overriding Clearance
+
+### Routes
 
 See [config/routes.rb](/config/routes.rb) for the default set of routes.
 
-Route overrides became more difficult with [changes made in Rails
-4][rails_routes]. For this reason, Clearance 1.5 introduces an option to disable
-all clearance routes, giving the user full control over routing and URL design.
+As of Clearance 1.5 it is recommended that you disable Clearance routes and take
+full control over routing and URL design. This ensures that your app's URL design
+won't be affected if the gem's routes and URL design are changed.
 
 To disable the routes, set `config.routes = false`. You can optionally run
 `rails generate clearance:routes` to dump a copy of the default routes into your
 application for modification.
 
-[rails_routes]: https://github.com/rails/rails/issues/11895
-
-Overriding controllers
-----------------------
+### Controllers
 
 See [app/controllers/clearance](/app/controllers/clearance) for the default
-behavior.
+behavior. Many protected methods were extracted in these controllers in an
+attempt to make overrides and hooks simpler.
 
-To override a Clearance controller, subclass it:
+To override a Clearance controller, subclass it and update the routes to
+point to your new controller (see the "Routes" section).
 
 ```ruby
 class PasswordsController < Clearance::PasswordsController
@@ -184,203 +179,87 @@ class SessionsController < Clearance::SessionsController
 class UsersController < Clearance::UsersController
 ```
 
-Don't forget to [override routes](#overriding-routes) to your new controllers!
-
-Then, override public methods:
-
-    passwords#create
-    passwords#edit
-    passwords#new
-    passwords#update
-    sessions#create
-    sessions#destroy
-    sessions#new
-    users#create
-    users#new
-
-Or, override private methods:
-
-    passwords#find_user_by_id_and_confirmation_token
-    passwords#find_user_for_create
-    passwords#find_user_for_edit
-    passwords#find_user_for_update
-    passwords#flash_failure_after_create
-    passwords#flash_failure_after_update
-    passwords#flash_failure_when_forbidden
-    passwords#forbid_missing_token
-    passwords#forbid_non_existent_user
-    passwords#url_after_create
-    passwords#url_after_update
-    sessions#url_after_create
-    sessions#url_after_destroy
-    users#flash_failure_after_create
-    users#url_after_create
-    users#user_from_params
-    users#user_params
-
-All of these controller methods redirect to `'/'` by default:
-
-    passwords#url_after_update
-    sessions#url_after_create
-    sessions#url_for_signed_in_users
-    users#url_after_create
-    application#url_after_denied_access_when_signed_in
-
-To override them all at once, change the global configuration:
-
-```ruby
-Clearance.configure do |config|
-  config.redirect_url = '/overridden'
-end
-```
-
-Overriding translations
------------------------
-
-All flash messages and email subject lines are stored in
-[i18n translations](http://guides.rubyonrails.org/i18n.html).
-Override them like any other translation.
-
-See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
-default behavior.
+### Redirects
 
-Overriding layouts
-----------------
+All of these controller methods redirect to
+`Clearance.configuration.redirect_url` (which is `/` by default):
 
-By default, Clearance uses your application's default layout. If you would like
-to change the layout that Clearance uses when rendering its views, simply specify
-the layout in an initializer.
-
-```ruby
-Clearance::PasswordsController.layout 'my_passwords_layout'
-Clearance::SessionsController.layout 'my_sessions_layout'
-Clearance::UsersController.layout 'my_admin_layout'
+```
+passwords#url_after_update
+sessions#url_after_create
+sessions#url_for_signed_in_users
+users#url_after_create
+application#url_after_denied_access_when_signed_in
 ```
 
-Overriding views
-----------------
-
-See [app/views](/app/views) for the default behavior.
-
-To override a view, create your own:
-
-    app/views/clearance_mailer/change_password.html.erb
-    app/views/passwords/create.html.erb
-    app/views/passwords/edit.html.erb
-    app/views/passwords/new.html.erb
-    app/views/sessions/_form.html.erb
-    app/views/sessions/new.html.erb
-    app/views/users/_form.html.erb
-    app/views/users/new.html.erb
-
-There is a shortcut to copy all Clearance views into your app:
-
-    rails generate clearance:views
-
-Overriding the model
---------------------
-
-See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
-
-To override the model, redefine public methods:
-
-    User.authenticate(email, password)
-    User#forgot_password!
-    User#reset_remember_token!
-    User#update_password(new_password)
-
-Or, redefine private methods:
-
-    User#email_optional?
-    User#generate_confirmation_token
-    User#generate_remember_token
-    User#normalize_email
-    User#password_optional?
+To override them all at once, change the global configuration of `redirect_url`.
+To change individual URLs, override the appropriate method.
 
-Overriding the password strategy
---------------------------------
+`application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
+Override this method to change this.
 
-By default, Clearance uses BCrypt encryption of the user's password.
+### Views
 
-See
-[lib/clearance/password_strategies/bcrypt.rb](/lib/clearance/password_strategies/bcrypt.rb)
-for the default behavior.
+See [app/views](/app/views) for the default behavior.
 
-Change your password strategy in `config/initializers/clearance.rb:`
+To override a view, create your own copy of it:
 
-```ruby
-Clearance.configure do |config|
-  config.password_strategy = Clearance::PasswordStrategies::SHA1
-end
 ```
-
-Clearance provides the following strategies:
-
-```ruby
-Clearance::PasswordStrategies::BCrypt
-Clearance::PasswordStrategies::BCryptMigrationFromSHA1
-Clearance::PasswordStrategies::Blowfish
-Clearance::PasswordStrategies::SHA1
+app/views/clearance_mailer/change_password.html.erb
+app/views/passwords/create.html.erb
+app/views/passwords/edit.html.erb
+app/views/passwords/new.html.erb
+app/views/sessions/_form.html.erb
+app/views/sessions/new.html.erb
+app/views/users/_form.html.erb
+app/views/users/new.html.erb
 ```
 
-The previous default password strategy was SHA1.
-
-Switching password strategies may cause your existing users to not be able to sign in.
+You can use the Clearance views generator to copy the default views to your
+application for modification.
 
-If you have an existing app that used the old `SHA1` strategy and you want to
-stay with SHA1, use
-[Clearance::PasswordStrategies::SHA1](/lib/clearance/password_strategies/sha1.rb).
+```shell
+$ rails generate clearance:views
+```
 
-If you have an existing app that used the old `SHA1` strategy and you want to
-switch to BCrypt transparently, use
-[Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
+### Layouts
 
-The SHA1 and Blowfish password strategies require an additional `salt` column in
-the `users` table. Run this migration before switching to SHA or Blowfish:
+By default, Clearance uses your application's default layout. If you would like
+to change the layout that Clearance uses when rendering its views, simply
+specify the layout in an initializer.
 
 ```ruby
-class AddSaltToUsers < ActiveRecord::Migration
-  def change
-    add_column :users, :salt, :string, limit: 128
-  end
-end
+Clearance::PasswordsController.layout "my_passwords_layout"
+Clearance::SessionsController.layout "my_sessions_layout"
+Clearance::UsersController.layout "my_admin_layout"
 ```
 
-You can write a custom password strategy that has two instance methods.
-In your `authenticated?` method, encrypt the password with your desired
-strategy, and then compare it to the `encrypted_password` that is provided by
-Clearance.
+### Translations
 
-```ruby
-module CustomPasswordStrategy
-  def authenticated?(password)
-    encrypted_password == encrypt(password)
-  end
+All flash messages and email subject lines are stored in [i18n translations]
+(http://guides.rubyonrails.org/i18n.html). Override them like any other
+translation.
 
-  def password=(new_password)
-  end
+See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
+default behavior.
 
-  private
+You can also install [clearance-i18n](https://github.com/thoughtbot/clearance-i18n)
+for access to additional, user-contributed translations.
 
-  def encrypt
-    # your encryption strategy
-  end
-end
+### User Model
 
-Clearance.configure do |config|
-  config.password_strategy = CustomPasswordStrategy
-end
-```
+See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
+You can override those methods as needed.
 
-Deliver password reset email in a background job
-------------------------------------------------
+### Deliver Email in Background Job
 
-Clearance has one mailer. It is used to reset the user's password.
+Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
+1.6 or greater, Clearance will use ActiveJob's `deliver_later` method to
+automatically take advantage of your configured queue.
 
-To deliver it in a background job using a queue system like [Delayed
-Job](https://github.com/collectiveidea/delayed_job), subclass
-`Clearance::PasswordsController` and define the behavior you need in its
-`deliver_email` method:
+If you are using an earlier version of Rails, you can override the
+`Clearance::Passwords` controller and define the behavior you need in the
+`deliver_email` method.
 
 ```ruby
 class PasswordsController < Clearance::PasswordsController
@@ -390,14 +269,13 @@ class PasswordsController < Clearance::PasswordsController
 end
 ```
 
-Then, override the route:
-
-```ruby
-resources :passwords, only: [:create]
-```
+## Extending Sign In
 
-Using the SignInGuard stack
--------------------
+By default, Clearance will sign in any user with valid credentials. If you need
+to support additional checks during the sign in process then you can use the
+SignInGuard stack. For example, using the SignInGuard stack, you could prevent
+suspended users from signing in, or require that users confirm their email
+address before accessing the site.
 
 `SignInGuard`s offer fine-grained control over the process of
 signing in a user. Each guard is run in order and hands the session off to
@@ -441,128 +319,128 @@ class EmailConfirmationGuard < Clearance::SignInGuard
 end
 ```
 
-Optional feature specs
-----------------------
+## Testing
+
+### Fast Feature Specs
+
+Clearance includes middleware that avoids wasting time spent visiting, loading,
+and submitting the sign in form. It instead signs in the designated user
+directly. The speed increase can be [substantial][backdoor].
+
+[backdoor]: http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door
 
-You can generate feature specs to help prevent regressions in Clearance's
-integration with your Rails app over time.
+Enable the Middleware in Test:
+
+```ruby
+# config/environments/test.rb
+MyRailsApp::Application.configure do
+  # ...
+  config.middleware.use Clearance::BackDoor
+  # ...
+end
+```
 
-Edit your `Gemfile` to include the dependencies:
+Usage:
 
 ```ruby
-gem 'capybara', '~> 2.0'
-gem 'factory_girl_rails', '~> 4.2'
-gem 'rspec-rails', '~> 2.13'
+visit root_path(as: user)
 ```
 
-Generate RSpec files:
+Additionally, if `User#to_param` is overridden, you can pass a block in
+order to override the default behavior:
 
-    rails generate rspec:install
+```ruby
+# config/environments/test.rb
+MyRailsApp::Application.configure do
+  # ...
+  config.middleware.use Clearance::BackDoor do |username|
+    Clearance.configuration.user_model.find_by(username: username)
+  end
+  # ...
+end
+```
 
-Generate Clearance specs:
+### Ready Made Feature Specs
 
-    rails generate clearance:specs
+If you're using RSpec, you can generate feature specs to help prevent
+regressions in Clearance's integration with your Rails app over time. These
+feature specs, will also require `factory_girl_rails`.
 
-Run the specs:
+To Generate the clearance specs, run:
 
-    rake
+```shell
+$ rails generate clearance:specs
+```
 
-Testing controller actions that require login
----------------------------------------------
+### Controller Test Helpers
 
-To test controller actions that are protected by `before_filter :require_login`,
-require Clearance's test helpers and matchers in your test suite.
+To test controller actions that are protected by `before_action :require_login`,
+require Clearance's test helpers in your test suite.
 
-For `rspec`, add this line to your `spec/spec_helper.rb`:
+For `rspec`, add the following line to your `spec/rails_helper.rb` or
+`spec/spec_helper` if `rails_helper` does not exist:
 
 ```ruby
-require 'clearance/rspec'
+require "clearance/rspec"
 ```
 
 For `test-unit`, add this line to your `test/test_helper.rb`:
 
 ```ruby
-require 'clearance/test_unit'
+require "clearance/test_unit"
 ```
 
 This will make `Clearance::Controller` methods work in your controllers
 during functional tests and provide access to helper methods like:
 
-    sign_in
-    sign_in_as(user)
-    sign_out
-
-And matchers like:
-
-    deny_access
-
-Example:
-
 ```ruby
-context 'a guest' do
-  before do
-    get :show
-  end
-
-  it { should deny_access }
-end
-
-context 'a user' do
-  before do
-    sign_in
-    get :show
-  end
-
-  it { should respond_with(:success) }
-end
+sign_in
+sign_in_as(user)
+sign_out
 ```
 
-You may want to customize the tests:
+### View and Helper Spec Helpers
+
+Does the view or helper you're testing reference `signed_in?`, `signed_out?` or
+`current_user`? If you `require 'clearance/rspec'`, you will have the following
+helpers available in your view specs:
 
 ```ruby
-it { should deny_access  }
-it { should deny_access(flash: 'Denied access.')  }
-it { should deny_access(redirect: sign_in_url)  }
+sign_in
+sign_in_as(user)
 ```
 
-Faster tests
-------------
+These will make the clearance view helpers work as expected by signing in either
+a new instance of your user model (`sign_in`) or the object you pass to
+`sign_in_as`. If you do not call one of these sign in helpers or otherwise set
+`current_user` in your view specs, your view will behave as if there is no
+current user: `signed_in?` will be false and `signed_out?` will be true.
 
-Clearance includes middleware that avoids wasting time spent visiting, loading,
-and submitting the sign in form. It instead signs in the designated
-user directly. The speed increase can be
-[substantial](http://robots.thoughtbot.com/post/37907699673/faster-tests-sign-in-through-the-back-door).
+## Contributing
 
-Configuration:
+Please see [CONTRIBUTING.md].
+Thank you, [contributors]!
 
-```ruby
-# config/environments/test.rb
-MyRailsApp::Application.configure do
-  # ...
-  config.middleware.use Clearance::BackDoor
-  # ...
-end
-```
+[CONTRIBUTING.md]: /CONTRIBUTING.md
+[contributors]: https://github.com/thoughtbot/clearance/graphs/contributors
 
-Usage:
+## License
 
-```ruby
-visit root_path(as: user)
-```
+Clearance is copyright © 2009 thoughtbot. It is free software, and may be
+redistributed under the terms specified in the [`LICENSE`] file.
 
-Credits
--------
+[`LICENSE`]: /LICENSE
 
-![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
+## About thoughtbot
 
-Clearance is maintained by [thoughtbot, inc](http://thoughtbot.com/community)
-and [contributors](https://github.com/thoughtbot/clearance/contributors) like
-you. Thank you!
+![thoughtbot](https://thoughtbot.com/logo.png)
 
-License
--------
+Clearance is maintained and funded by thoughtbot, inc.
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
 
-Clearance is copyright © 2009 thoughtbot. It is free software, and may be
-redistributed under the terms specified in the `LICENSE` file.
+We love open source software!
+See [our other projects][community] or
+[hire us][hire] to design, develop, and grow your product.
 
-The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+[community]: https://thoughtbot.com/community?utm_source=github
+[hire]: https://thoughtbot.com/hire-us?utm_source=github