Skip to content
Rails authentication with email & password.
Pull request Compare This branch is 21 commits ahead, 689 commits behind thoughtbot:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Rails authentication with email & password.

We have clearance, Clarence.


Bugs, Patches

Fork away and create a Github Issue.


Clearance is a Rails engine. It works with versions of Rails greater than 2.3.

Install it as a gem however you like to install gems. Gem Bundler example:

gem "authlogic"
gem "clearance"

Make sure the development database exists and run the generator:

script/generate clearance


  • inserts Clearance::User into your User model
  • inserts Clearance::UserSession into your UserSession model
  • inserts Clearance::Authentication into your ApplicationController
  • inserts Clearance::Routes.draw(map) into your config.routes.rb
  • created a migration that either creates a users table or adds only missing columns
  • prints further instructions

Make sure flash messages are shown in your layout:

<div id="flash">
  <% flash.each do |key, value| -%>
    <div id="flash_<%= key %>"><%=h value %></div>
  <% end -%>


This upgrade comes with a dependency on Authlogic, so be sure to add that to
your environment.rb:

config.gem 'authlogic', :version => '2.1.3'

The database field confirmation_token has changed to perishable_token. You must
add this migration if upgrading:

rename_column :users, :confirmation_token, :perishable_token
add_index :users, :perishable_token

The sessions parameter has changed to user_session. If you have customized
sessions/new.html.erb be sure to modify it:

<% form_for @user_session, :url => session_path do |form| %>
<% end %>
  def new
    @user_session =


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 end end

Subclass and override any Clearance-provided controller as needed:

class SessionsController < Clearance::SessionsController def url_after_create new_blog_post_path end end

Actions that redirect (create, update, and destroy) in Clearance controllers
can be overriden 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.
thoughtbot’s opinion is that you should test its integration with your app
using Cucumber.

You wil need cucumber, cucumber-rails, and factory_girl for this:

config.gem 'cucumber'
config.gem 'cucumber-rails', :lib => false
config.gem 'factory_girl'

Run the Cucumber generator (if you haven’t already) and Clearance’s feature

script/generate cucumber
script/generate clearance_features

All of the files generated should be new with the exception of the
features/support/paths.rb file. If you have not modified your paths.rb then you
will be okay to replace it with this one. If you need to keep your paths.rb
file then add these locations in your paths.rb manually:

def path_to(page_name)
  case page_name
  when /the sign up page/i
  when /the sign in page/i
  when /the password reset request page/i

Optional Formtastic views

Clearance has another generator to generate Formastic views:

script/generate clearance_views

Its implementation is designed so that other view styles can be generated if
the community wants it. However, we haven’t needed them so you’ll have to write
the patch and send it back if you want other styles (such as Haml).


Clearance was extracted out of Hoptoad. We merged the
authentication code from two of thoughtbot’s clients’ Rails apps and have since
used it each time we need authentication. The following people have improved
the library. Thank you!

Dan Croak, Mike Burns, Jason Morrison, Joe Ferris, Eugene Bolshakov, Nick
Quaranto, Josh Nichols, Mike Breen, Marcel Görner, Bence Nagy, Ben Mabey, Eloy
Duran, Tim Pope, Mihai Anca, Mark Cornick, Shay Arnett, Joshua Clayton, Mustafa
Ekim, Jon Yurek, Anuj Dutta, and Chad Pytel.

Something went wrong with that request. Please try again.