Clearance

Rails authentication & authorization with email & password.

Clearance was extracted out of Hoptoad.

Help

Documentation at RDoc.info.
Patches and bugs at Github Issues.
Mailing list at Google Groups.

Installation

Clearance is a Rails engine for Rails 3. It is currently tested against Rails 3.0.9 and Rails 3.1.0.rc4.

Include the gem in your Gemfile:

gem "clearance"

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

rails generate clearance:install

This:

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

Follow the instructions that are output from the generator.

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

Usage

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

class WidgetsController < ApplicationController
  before_filter :authorize

  def index
    @widgets = Widget.all
  end
end

If you want to reference the current user in a controller, view, or helper, use the current_user method.

def index
  current_user.articles
end

If you want to know whether the current user is signed in or out, you can use these methods in controllers, views, or helpers:

signed_in?
signed_out?

Typically, you want to have something like this in your app, maybe in a layout:

<% if signed_in? %>
  <%= current_user.email %>
  <%= link_to "Sign out", sign_out_path, :method => :delete %>
<% else %>
  <%= link_to "Sign in", sign_in_path %>
<% end %>

If you ever want to authenticate the user some place other than sessions/new, maybe in an API:

User.authenticate("[email protected]", "password")

Clearance will deliver one email on your app's behalf: when a user resets their password. Therefore, you should change the default email address that email comes from:

# config/initializers/clearance.rb
Clearance.configure do |config|
  config.mailer_sender = "[email protected]"
end

Overriding defaults

Clearance is intended to be small, simple, well-tested, and easy to override defaults.

Overriding routes

See config/routes.rb for the default behavior.

To override a Clearance route, redefine it:

resource :session, :controller => 'sessions'

Overriding controllers

See app/controllers/clearance for the default behavior.

To override a Clearance controller, subclass it:

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

  def url_after_create
    my_special_path
  end
end

You may want to override entire actions:

def new
end

Or, you may want to override private methods that actions use:

url_after_create
url_after_update
url_after_destroy
flash_failure_after_create
flash_failure_after_update
flash_failure_when_forbidden
forbid_missing_token
forbid_non_existent_user

Overriding translations

All flash messages and email subject lines are stored in i18n translations. Override them like any other translation.

Overriding views

See app/views for the default behavior.

To override those views, create them in your own app/views directory.

There is a shortcut to copy all Clearance views into your app:

rails generate clearance:views

Overriding the model

If you want to override the model behavior, you can include sub-modules of Clearance::User:

extend  Clearance::User::ClassMethods
include Clearance::User::Validations
include Clearance::User::Callbacks

ClassMethods contains the User.authenticate(email, password) method.

Validations contains validations for email and password.

Callbacks contains ActiveRecord callbacks downcasing the email and generating a remember token.

Overriding the password strategy

By default, Clearance uses SHA1 encryption of the user's password. You can provide your own password strategy by creating a module that conforms to an API of two instance methods:

def authenticated?
end

def encrypt_password
end

See lib/clearance/password_strategies/sha1.rb for the default behavior.

Once you have an API-compliant module, load it with:

Clearance.configure do |config|
  config.password_strategy = MyPasswordStrategy
end

Optional Cucumber features

Clearance's Cucumber features are dependent on:

Cucumber
Capybara
RSpec
Factory Girl

As your app evolves, you want to know that authentication still works. If you've installed Cucumber into your app:

rails generate cucumber:install

Then, you can use the Clearance features generator:

rails generate clearance:features

Edit your Gemfile to include:

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

Optional test matchers

Clearance comes with test matchers that are compatible with RSpec and Test::Unit.

To use them, require the test matchers. For example, in spec/support/clearance.rb:

require 'clearance/testing'

You'll then have access to methods like:

sign_in
sign_in_as(user)
sign_out

And matchers like:

deny_access

Example:

context "a visitor" do
  before { get :show }
  it     { should deny_access }
end

context "a user" do
  before do
    sign_in
    get :show
  end

  it { should respond_with(:success) }
end

Contributing

Please see CONTRIBUTING.md for details.

Credits

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.