thoughtbot/clearance: Rails email and password authentication without the weight

What Clearance solves, and for whom

Clearance is a Rails engine that provides email and password authentication. The README states the intent plainly: the library is meant to be small, simple, and well-tested, with opinionated defaults that are easy to override. That sentence is the whole pitch, and it is also the constraint. If your application needs a sign-in form, a password reset by email, a remember-me cookie and a way to gate controller actions, Clearance covers that ground and stops there.

The audience is a Rails team that has decided not to build authentication from scratch and also not to adopt a framework with a wider feature set. The gem is tested against Rails >= 7.2 and Ruby >= 3.3.11, so it tracks current Rails rather than supporting older lines. A team maintaining an application on Rails 6 or Ruby 3.0 cannot use it without upgrading first.

What you get is a set of controllers, views, routes and a mailer, all inside the gem, plus a User concern and a controller concern that the install generator wires into your application. What you do not get is a user management interface, a social login, or anything resembling an authorization policy. Clearance answers who is signed in. It does not answer what that person is allowed to do.

How the engine wires itself into a Rails app

Clearance ships as a Rails engine, so its controllers, views and routes live in the gem and are mounted through the host application's router. The install generator performs four edits, according to the README: it inserts Clearance::User into your User model, inserts Clearance::Controller into your ApplicationController, creates an initializer file, and creates a migration that either creates a users table or adds the necessary columns to an existing one.

That last point matters more than it looks. Clearance expects to own a specific set of columns on whatever table backs your user model. If you already have a users table with an email column and a password digest, the generator tries to reconcile the schema rather than replace it. You should read the generated migration before running it.

The runtime data flow is conventional Rails. A request hits a Clearance controller, which authenticates against the configured password strategy (BCrypt by default, per the initializer example), writes a session, and optionally sets a remember token cookie. Clearance also places its session into the Rack environment under the key :clearance, which the README demonstrates with a middleware that calls env[:clearance].signed_in? and env[:clearance].current_user. That hook is the cleanest integration point for anything outside the Rails request cycle.

Access control happens at two levels. In controllers, a before_action :require_login filter guards actions. At the routing layer, Clearance provides constraints such as Clearance::Constraints::SignedIn and Clearance::Constraints::SignedOut, and the README shows SignedIn accepting a block that receives the user, which is how you express something like an admin-only root route.

Installing Clearance and getting a first guarded page

Start by adding the gem to your Gemfile and running bundle. The README gives the dependency line exactly as follows.

gem "clearance"

After bundling, run the install generator. This is the step that modifies your application, so run it on a branch.

rails generate clearance:install

You should see the generator report the files it creates and the two files it modifies: the User model and the ApplicationController. Open the generated migration and the generated config/initializers/clearance.rb before you run the migration.

The initializer is where the defaults live. The README lists the full set of options; a minimal edit is to change the mailer sender, since the default is a placeholder address that would appear in the from header of password reset emails.

Clearance.configure do |config|
  config.mailer_sender = "[email protected]"
end

With that in place, guarding a controller action is one line. The README's own example puts the filter on an ArticlesController and then reads current_user inside the action.

class ArticlesController < ApplicationController
  before_action :require_login

  def index
    current_user.articles
  end
end

In views, the helper methods current_user, signed_in? and signed_out? are available. A signed-out visitor hitting that index action is redirected rather than shown an error, and the redirect target is governed by the configuration described in the next section.

Redirects, routes and the override surface

Clearance's redirect behavior is not a single setting. The README separates success methods from failure methods. The success methods (passwords#url_after_update, sessions#url_after_create, sessions#url_for_signed_in_users, users#url_after_create, and application#url_after_denied_access_when_signed_in) all point at Clearance.configuration.redirect_url, which defaults to "/". You can change them all at once through that config value, or override individual methods in a subclassed controller.

The failure methods are application#url_after_denied_access_when_signed_out and sessions#url_after_destroy. Each has its own configuration key, url_after_denied_access_when_signed_out and url_after_destroy, and both default to nil. When left at nil, they fall back to sign_in_url for backwards compatibility, as the README explains. That fallback is worth knowing about: setting one of these keys to nil does not mean "no redirect", it means "use the historical default".

The README recommends disabling the gem's routes entirely and taking control of URL design yourself, a recommendation it dates to Clearance 1.5. The reasoning given is that your application's URLs will not shift if the gem's routes change. To do that, set the routes option to false in the initializer, and optionally run rails generate clearance:routes to dump a copy of the default routes into your application so you can edit them in place.

The same override pattern applies to controllers and views. Controllers are subclassed (PasswordsController, SessionsController, UsersController are the three the README names) and the routes are repointed at the subclass. Views are replaced by copying the file into your application at the matching path, for example app/views/clearance_mailer/change_password.html.erb. There is no view resolver trickery here; you copy and edit.

Where Clearance is the wrong choice

The README documents email and password authentication. It does not document OAuth providers, SAML, multi-factor authentication, API tokens, or account lockout after repeated failed attempts. If your product roadmap includes any of those, you are choosing to build them on top of Clearance rather than getting them from it, and you should price that work before you commit.

The second limitation is the generator. Inserting Clearance::User into your User model and Clearance::Controller into your ApplicationController is convenient the first time and awkward the tenth. It means the gem has an opinion about your model's inheritance and your base controller's behavior. An application whose ApplicationController already carries a large amount of shared logic will want to review what the generator adds before accepting it.

The third is the schema. Because the migration either creates a users table or adds columns to an existing one, projects with a non-standard user table (a different primary key, a separate credentials table, or email stored on a profile record) will need to adapt the generated migration. The README does not document rollback behavior for the generator, so treat the migration as something to inspect rather than something to trust.

Finally, cookie configuration deserves attention. The initializer exposes cookie_domain, cookie_path, cookie_expiration, httponly, same_site, secure_cookie and signed_cookie. The default for secure_cookie is Rails.configuration.force_ssl, and same_site defaults to nil. If your application terminates TLS somewhere other than the Rails process, verify that force_ssl reflects reality, because the default couples the two.

Alternatives and the difference in approach

The most direct alternative in the Rails ecosystem is Devise, and the difference is scope rather than quality. Devise is built as a set of modules you opt into, covering confirmable accounts, lockable accounts, omniauth integration, recoverable passwords and more, with a large configuration surface and its own set of generators. Clearance makes the opposite bet: one authentication model, a short configuration file, and an explicit recommendation that you disable its routes and own your URLs. If you want a feature to be a configuration flag, Devise is the closer fit. If you want to read the entire authentication path in an afternoon, Clearance is.

A second alternative is Rails' own has_secure_password plus a hand-written sessions controller. That gives you complete control and no engine, at the cost of writing the password reset flow, the mailer, the remember token and the access-control filter yourself. Clearance is essentially that work, pre-written and tested, with the override points left open.

The Rack integration is where Clearance distinguishes itself from a purely Rails-shaped solution. Exposing env[:clearance] means middleware and other Rack applications can ask whether a request is signed in without going through a Rails controller. The README's Bubblegum::Middleware example is short, but it describes a real capability that a hand-rolled controller-based approach does not offer by default.

Maintenance, licence and upgrade cost

Clearance is MIT licensed, which places few restrictions on commercial use and modification. The repository is not archived, and the most recent push was on 2026-07-16. The release history shows v2.12.0 on 2026-04-17, v2.11.0 on 2025-09-26 and v2.10.0 on 2025-03-28, which is a roughly twice-a-year cadence rather than a constant stream of patches.

That cadence has a practical consequence for the override strategy the README recommends. Because you are encouraged to disable the gem's routes and copy its views into your application, upgrades will not automatically deliver changes to those files. You get the gem's controllers and models, but your routes and views are yours to maintain, and a security fix that lands in a default view will not reach a copy you made two years ago. The app/views path in the repository is the reference you diff against.

The version support floor is the other cost. Clearance is tested against Rails >= 7.2 and Ruby >= 3.3.11. An application on an older Rails line has to upgrade the framework before it can adopt the gem, and after adoption it has to keep pace with whatever floor the gem raises next. There is no long-term support branch described in the README.

The repository includes a SECURITY.md, a CHANGELOG.md and a RELEASING.md, which is a reasonable signal that releases are a documented process rather than an ad hoc one. It does not, on its own, tell you how quickly a reported vulnerability gets fixed. That is a question to answer from the project's issue tracker and release notes before you depend on it.

Editorial conclusion

Adopt Clearance when you want email and password sign-in with a small surface you can read, and you are comfortable letting a generator edit User and ApplicationController. Do not adopt it if you need OAuth, multi-factor authentication or an admin UI, since the README documents none of those. Before committing, run the install generator on a branch and inspect the migration and the initializer it writes, then decide whether you want to disable the built-in routes with config.routes = false and own the URL design yourself.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thoughtbot/clearance on GitHub