---
title: 'Clearance: Rails authentication with email and password'
teaser:
tags: news,web,rails,clearance
author: Dan Croak
published_on: 2009-02-09
---

Authentication is a common pattern in Rails apps. Thus, there have been many
authentication plugins. We've tried `acts_as_authenticated` and
`restful_authentication` over
the years.

We found that user authentication is hard to generalize. Most abstracted
authentication plugins had both too much and too little for us.

We then tried writing authentication from scratch on our clients' Rails apps for
about a year. We felt better about test coverage but it was still a pain to
re-write similar code. App after app, we talked about extracting common code
into a library. Each time we resisted.

After a while, we thought that maybe 60% of authentication could be re-used. We
extracted [Hoptoad](http://hoptoadapp.com)'s authentication, then merged code
from two of our clients' apps. We named the gem
[Clearance](http://github.com/thoughtbot/clearance).

On the first attempt, we went overboard on re-use. We backed off and wrote hooks
in places we were finding logical extension points. For the past few months,
patches have trickled in from Github and we've carefully included code that fits
in the "60%".

We recently started a new project. In the process, we've polished the gem and
are happy to announce its official release.

## Clearance

- Sign up
- Confirm email
- Sign in
- Sign out
- Reset password

Get it on [Github](http://github.com/thoughtbot/clearance).

## Modules, Shoulda, and Factory Bot

Clearance is focused on maintainability of your application's authentication
code.

- Include comprehensive Shoulda and Factory Bot tests in your Rails app's test
  suite
- Encapsulate authentication logic in modules which are included in your
  controllers, models, and tests.

This approach keeps your Rails application's code clean and alerts you if you
ever break your authentication code.

Due to the work we've been doing to make Shoulda test framework-agnostic, you
will be able to use RSpec in the 0.5.0 release of Clearance.

Test::Unit and [Cucumber](http://github.com/aslakhellesoy/cucumber) features are
also supported:

    script/generate clearance
    script/generate clearance_features

## Conventions

To keep our approach simple, we made a series of design decisions:

- User model required.
- User model uses [attr_accessible].
- Authenticate by email (not username) and password.
- Vocabulary restricted to a trinity: "sign up", "sign in", "sign out"

[attr_accessible]: http://api.rubyonrails.org/classes/ActiveRecord/Base.html#M001981

## Beyond

Clearance does not try to be a Swiss Army knife but it does have some
[hooks](http://wiki.github.com/thoughtbot/clearance/usage) if you want [admin
roles](http://wiki.github.com/thoughtbot/clearance/admin), [sign up and sign in
by username in addition to
email](http://wiki.github.com/thoughtbot/clearance/sign-up-sign-in-with-user-name),
or something else.

Please report bugs and request features on [GitHub
Issues](https://github.com/thoughtbot/clearance/issues).