Fetching contributors…
Cannot retrieve contributors at this time
140 lines (89 sloc) 3.74 KB


Rails authentication with email & password.

We have clearance, Clarence.

Clearance was extracted out of Hoptoad. We merged the authentication code from two of thoughtbot's client Rails apps and have since used it each time we needed authentication.


Bugs, Patches

Fork away and create a Github Issue.


Clearance is a Rails engine for Rails 3.

Use the 0.8.x series of Clearance if you have a Rails 2 app.

Include the gem in your Gemfile:

gem "clearance"

Make sure the development database exists, then run the generator:

rails generate clearance


  • inserts Clearance::User into your User model
  • inserts Clearance::Authentication into your ApplicationController
  • creates a migration that either creates a users table or adds only missing columns


If you want to authenticate users for a controller action, use the authenticate method in a before_filter.

class WidgetsController < ApplicationController
  before_filter :authenticate
  def index
    @widgets = Widget.all


To change any of provided actions, subclass a Clearance controller...

class SessionsController < Clearance::SessionsController
  def new
    # my special new action
  def url_after_create

and add your route in config/routes.rb:

resource :session, :controller => 'sessions'

See config/routes.rb for all the routes Clearance provides.

Actions that redirect (create, update, and destroy) in Clearance controllers can be overridden by re-defining url_after_(action) methods as seen above.

Optional Cucumber features

As your app evolves, you want to know that authentication still works. Our opinion is that you should test its integration with your app using Cucumber.

Run the Cucumber generator and Clearance feature generator:

script/rails generate cucumber
script/rails generate clearance_features

Edit your Gemfile to include:

gem 'factory_girl_rails'

Edit your config/enviroments/cucumber.rb to include the following:

config.action_mailer.default_url_options = { :host => 'localhost:3000' }

Then run rake!

Optional Formtastic views

We use & recommend Formtastic.

Clearance has another generator to generate Formastic views:

script/rails generate clearance_views

Its implementation is designed so other view styles (Haml?) can be generated.


Clearance is intended to be small, simple, well-tested, and easy to extend. Check out some of the ways people have extended Clearance:



Clearance is maintained and funded by thoughtbot, inc

Thank you to all the contributors!

The names and logos for thoughtbot are trademarks of thoughtbot, inc.


Clearance is Copyright © 2009-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the LICENSE file.