Clearance

Simple, complete Ruby web app authentication.

We have clearance, Clarence.

Gem installation (Rails 2.1+)

In config/environments/test.rb:

config.gem 'thoughtbot-shoulda', :lib => 'shoulda', :source => "http://gems.github.com" 
config.gem 'thoughtbot-factory_girl', :lib => 'factory_girl', :source => "http://gems.github.com"

In config/environment.rb:

config.gem "thoughtbot-clearance", :lib => 'clearance', :source => 'http://gems.github.com/'

Then:

rake gems:install
rake gems:unpack

Generator

In a greenfield application, just run the generator:

script/generate clearance

This will create:

app/controllers/confirmations_controller.rb
app/controllers/passwords_controller.rb
app/controllers/sessions_controller.rb
app/controllers/users_controller.rb
app/models/user.rb
app/models/user_mailer.rb
app/views/confirmations/new.html.erb
app/views/passwords/edit.html.erb
app/views/passwords/new.html.erb
app/views/sessions/new.html.erb
app/views/user_mailer/change_password.html.erb
app/views/user_mailer/confirmation.html.erb
app/views/users/_form.html.erb
app/views/users/edit.html.erb
app/views/users/new.html.erb
test/functional/confirmations_controller_test.rb
test/functional/passwords_controller_test.rb
test/functional/sessions_controller_test.rb
test/functional/users_controller_test.rb
test/unit/user_mailer_test.rb
test/unit/user_test.rb

Add the corresponding Clearance module for any file(s) you don’t want to override. They are namespaced exactly like the directory structure of a Rails app:

app/models/user.rb already exists.
include Clearance::App::Models::User

Tests

The tests use Shoulda >= 2.0.4 and Factory Girl. You should create a User Factory:

Factory.sequence :email do |n|
  "user#{n}@example.com" 
end

Factory.define :user do |user|
  user.email { Factory.next :email }
  user.password "password" 
  user.password_confirmation "password" 
end

In test/test_helper.rb:

class Test::Unit::TestCase
  self.use_transactional_fixtures = true
  self.use_instantiated_fixtures  = false
  include Clearance::Test::TestHelper
end

Controllers

In app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  helper :all
  protect_from_forgery
  include Clearance::App::Controllers::ApplicationController
end

Migration

Your users table needs a few columns.

create_table(:users) do |t|
  t.string :email
  t.string :crypted_password, :limit => 40
  t.string :salt, :limit => 40
  t.string :remember_token
  t.datetime :remember_token_expires_at
  t.boolean :confirmed, :default => false, :null => false
end

add_index :users, [:email, :crypted_password]
add_index :users, [:id, :salt]
add_index :users, :email
add_index :users, :remember_token

Routes

map.resources :users
map.resource :session
map.resources :users, :has_one => :password
map.resources :users, :has_one => :confirmation
map.resources :passwords
map.root :controller => 'sessions', :action => 'new'

Environments

In config/environments/test.rb and config/environments/development.rb:

HOST = "localhost"

In config/environment.rb:

DO_NOT_REPLY = "donotreply@example.com" 
PROJECT_NAME = "my_app_name"

Authors

• thoughtbot, inc.
• Dan Croak
• Jason Morrison
• Mike Burns
• Josh Nichols
• Mike Breen