README.md in clearance-1.0.0.rc7 vs README.md in clearance-1.0.0.rc8
- old
+ new
@@ -1,12 +1,10 @@
Clearance
=========
-[](http://travis-ci.org/thoughtbot/clearance?branch=master)
-[](https://codeclimate.com/github/thoughtbot/clearance)
+[](http://travis-ci.org/thoughtbot/clearance?branch=master)
+[](https://codeclimate.com/github/thoughtbot/clearance)
[](https://gemnasium.com/thoughtbot/clearance)
Rails authentication with email & password.
Clearance was extracted out of [Airbrake](http://airbrake.io/). It is intended
@@ -17,16 +15,18 @@
Read [CONTRIBUTING.md](/CONTRIBUTING.md) to contribute.
Install
-------
-Clearance is a Rails engine tested against [Rails 3.x](/Appraisals) on Ruby
-1.9.x and Ruby 2.0.x.
+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:
- gem 'clearance', '1.0.0.rc7'
+```ruby
+gem 'clearance', '1.0.0.rc7'
+```
Bundle:
bundle --binstubs
@@ -51,105 +51,124 @@
Configure
---------
Override any of these defaults in `config/initializers/clearance.rb`:
- Clearance.configure do |config|
- config.cookie_expiration = lambda { 1.year.from_now.utc }
- config.secure_cookie = false
- config.mailer_sender = 'reply@example.com'
- config.password_strategy = Clearance::PasswordStrategies::BCrypt
- config.user_model = User
- config.redirect_path = '/'
- end
+```ruby
+Clearance.configure do |config|
+ config.cookie_expiration = lambda { 1.year.from_now.utc }
+ config.httponly = false
+ config.secure_cookie = false
+ config.mailer_sender = 'reply@example.com'
+ config.password_strategy = Clearance::PasswordStrategies::BCrypt
+ config.user_model = User
+ config.redirect_url = '/'
+end
+```
Use
---
Use `current_user`, `signed_in?`, and `signed_out?` in controllers, views, and
helpers. For example:
- - if signed_in?
- = current_user.email
- = link_to 'Sign out', sign_out_path, method: :delete
- - else
- = link_to 'Sign in', sign_in_path
+```haml
+- if signed_in?
+ = current_user.email
+ = link_to 'Sign out', sign_out_path, method: :delete
+- else
+ = link_to 'Sign in', sign_in_path
+```
To authenticate a user elsewhere than `sessions/new` (like in an API):
- User.authenticate 'email@example.com', 'password'
+```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:
- Clearance.configure do |config|
- config.mailer_sender = 'reply@example.com'
- end
+```ruby
+Clearance.configure do |config|
+ config.mailer_sender = 'reply@example.com'
+end
+```
Use `authorize` to control access in controllers:
- class ArticlesController < ApplicationController
- before_filter :authorize
+```ruby
+class ArticlesController < ApplicationController
+ before_filter :authorize
- def index
- current_user.articles
- end
- end
+ def index
+ current_user.articles
+ end
+end
+```
Or, you can authorize users in `config/routes.rb`:
- Blog::Application.routes.draw do
- constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
- root to: 'admin'
- end
+```ruby
+Blog::Application.routes.draw do
+ constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
+ root to: 'admin'
+ end
- constraints Clearance::Constraints::SignedIn.new do
- root to: 'dashboard'
- end
+ constraints Clearance::Constraints::SignedIn.new do
+ root to: 'dashboard'
+ end
- constraints Clearance::Constraints::SignedOut.new do
- root to: 'marketing'
- end
- end
+ constraints Clearance::Constraints::SignedOut.new do
+ root to: 'marketing'
+ end
+end
+```
Clearance adds its session to the Rack environment hash so middleware and other
Rack applications can interact with it:
- class Bubblegum::Middleware
- def initialize(app)
- @app = app
- end
+```ruby
+class Bubblegum::Middleware
+ def initialize(app)
+ @app = app
+ end
- def call(env)
- if env[:clearance].signed_in?
- env[:clearance].current_user.bubble_gum
- end
-
- @app.call(env)
- end
+ def call(env)
+ if env[:clearance].signed_in?
+ env[:clearance].current_user.bubble_gum
end
+ @app.call(env)
+ end
+end
+```
+
Overriding routes
-----------------
See [config/routes.rb](/config/routes.rb) for the default behavior.
To override a Clearance route, redefine it:
- resource :session, controller: 'sessions'
+```ruby
+resource :session, controller: 'sessions'
+```
Overriding controllers
----------------------
See [app/controllers/clearance](/app/controllers/clearance) for the default
behavior.
To override a Clearance controller, subclass it:
- class PasswordsController < Clearance::PasswordsController
- class SessionsController < Clearance::SessionsController
- class UsersController < Clearance::UsersController
+```ruby
+class PasswordsController < Clearance::PasswordsController
+class SessionsController < Clearance::SessionsController
+class UsersController < Clearance::UsersController
+```
Then, override public methods:
passwords#create
passwords#edit
@@ -179,10 +198,25 @@
sessions#url_after_destroy
users#flash_failure_after_create
users#url_after_create
users#user_from_params
+All of these controller methods redirect to `'/'` by default:
+
+ passwords#url_after_update
+ sessions#url_after_create
+ 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 = '/overriden'
+end
+```
+
Overriding translations
-----------------------
All flash messages and email subject lines are stored in
[i18n translations](http://guides.rubyonrails.org/i18n.html).
@@ -216,22 +250,22 @@
See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
To override the model, redefine public methods:
- .authenticate(email, password)
- #forgot_password!
- #reset_remember_token!
- #update_password(new_password)
+ User.authenticate(email, password)
+ User#forgot_password!
+ User#reset_remember_token!
+ User#update_password(new_password)
Or, redefine private methods:
- #email_optional?
- #generate_confirmation_token
- #generate_remember_token
- #normalize_email
- #password_optional?
+ User#email_optional?
+ User#generate_confirmation_token
+ User#generate_remember_token
+ User#normalize_email
+ User#password_optional?
Overriding the password strategy
--------------------------------
By default, Clearance uses BCrypt encryption of the user's password.
@@ -240,20 +274,24 @@
[lib/clearance/password_strategies/bcrypt.rb](/lib/clearance/password_strategies/bcrypt.rb)
for the default behavior.
Change your password strategy in `config/initializers/clearance.rb:`
- Clearance.configure do |config|
- config.password_strategy = Clearance::PasswordStrategies::SHA1
- end
+```ruby
+Clearance.configure do |config|
+ config.password_strategy = Clearance::PasswordStrategies::SHA1
+end
+```
Clearance provides the following strategies:
- config.password_strategy = Clearance::PasswordStrategies::BCrypt
- config.password_strategy = Clearance::PasswordStrategies::BCryptMigrationFromSHA1
- config.password_strategy = Clearance::PasswordStrategies::Blowfish
- config.password_strategy = Clearance::PasswordStrategies::SHA1
+```ruby
+Clearance::PasswordStrategies::BCrypt
+Clearance::PasswordStrategies::BCryptMigrationFromSHA1
+Clearance::PasswordStrategies::Blowfish
+Clearance::PasswordStrategies::SHA1
+```
The previous default password strategy was SHA1.
Switching password strategies may cause your existing users to not be able to sign in.
@@ -266,72 +304,71 @@
[Clearance::PasswordStrategies::BCryptMigrationFromSHA1](/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb).
The SHA1 and Blowfish password strategies require an additional `salt` column in
the `users` table. Run this migration before switching to SHA or Blowfish:
- class AddSaltToUsers < ActiveRecord::Migration
- def change
- add_column :users, :salt, :string, limit: 128
- end
- end
+```ruby
+class AddSaltToUsers < ActiveRecord::Migration
+ def change
+ add_column :users, :salt, :string, limit: 128
+ end
+end
+```
You can write a custom password strategy that has two instance methods:
- module CustomPasswordStrategy
- def authenticated?
- end
+```ruby
+module CustomPasswordStrategy
+ def authenticated?
+ end
- def password=(new_password)
- end
- end
+ def password=(new_password)
+ end
+end
- Clearance.configure do |config|
- config.password_strategy = CustomPasswordStrategy
- end
+Clearance.configure do |config|
+ config.password_strategy = CustomPasswordStrategy
+end
+```
-Optional Integration tests
---------------------------
+Optional feature specs
+----------------------
-Clearance's integration tests are dependent on:
+You can generate feature specs to help prevent regressions in Clearance's
+integration with your Rails app over time.
-* Capybara
-* Factory Girl
-* RSpec
+Edit your `Gemfile` to include the dependencies:
-As your app evolves, you want to know that authentication still works. We
-include support for RSpec integration tests.
+```ruby
+gem 'capybara', '~> 2.0'
+gem 'factory_girl_rails', '~> 4.2'
+gem 'rspec-rails', '~> 2.13'
+```
-If you've installed [RSpec](https://github.com/rspec/rspec) in your app:
+Generate RSpec files:
rails generate rspec:install
-Then, you can use the Clearance specs generator:
+Generate Clearance specs:
rails generate clearance:specs
-Edit your Gemfile to include:
+Run the specs:
- gem 'factory_girl_rails'
-
-Edit `config/enviroments/test.rb` to include the following:
-
- config.action_mailer.default_url_options = { host: 'localhost:3000' }
-
-Then run your tests!
-
rake
-Testing
--------
+Testing authorized controller actions
+-------------------------------------
-If you want to write Rails functional tests or controller specs with Clearance,
-you'll need to require the included test helpers and matchers.
+To test controller actions that are protected by `before_filter :authorize`,
+include Clearance's test helpers and matchers in `spec/support/clearance.rb` or
+`test/test_helper.rb`:
-For example, in `spec/support/clearance.rb` or `test/test_helper.rb`:
+```ruby
+require 'clearance/testing'
+```
- require 'clearance/testing'
-
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)
@@ -341,39 +378,68 @@
deny_access
Example:
- context 'a guest' do
- before do
- get :show
- end
+```ruby
+context 'a guest' do
+ before do
+ get :show
+ end
- it { should deny_access }
- end
+ it { should deny_access }
+end
- context 'a user' do
- before do
- sign_in
- get :show
- end
+context 'a user' do
+ before do
+ sign_in
+ get :show
+ end
- it { should respond_with(:success) }
- end
+ it { should respond_with(:success) }
+end
+```
You may want to customize the tests:
- it { should deny_access }
- it { should deny_access(flash: 'Denied access.') }
- it { should deny_access(redirect: sign_in_url) }
+```ruby
+it { should deny_access }
+it { should deny_access(flash: 'Denied access.') }
+it { should deny_access(redirect: sign_in_url) }
+```
+Faster tests
+------------
+
+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).
+
+Configuration:
+
+```ruby
+# config/environments/test.rb
+MyRailsApp::Application.configure do
+ # ...
+ config.middleware.use Clearance::BackDoor
+ # ...
+end
+```
+
+Usage:
+
+```ruby
+visit root_path(as: user)
+```
+
Credits
-------
Clearance is maintained by [thoughtbot, inc](http://thoughtbot.com/community)
-and [contributors](/thoughtbot/clearance/contributors) like you. Thank you!
+and [contributors](/thoughtbot/clearance/graphs/contributors) like you. Thank you!
License
-------
Clearance is copyright © 2009-2013 thoughtbot. It is free software, and may be