Library / SDK
thoughtbot/clearance avatar
thoughtbot/clearance

Clearance: a Rails auth engine that recommends you turn off its own routes

Rails authentication with email & password.

3,730 stars462 forksRubyMIT

At a glance

What is it?
Clearance is thoughtbot's Rails engine for email and password authentication, MIT licensed and tested against Rails 7.2 and Ruby 3.3.11. It is small and opinionated, and the most useful thing in its documentation is the advice to stop using the routes it installs by default, plus the details of which redirect settings fall back where.
Who is it for?
Clearance fits an application that wants conventional session authentication with sensible defaults and no surprises, and it fits best if you are willing to take ownership of the parts it tells you to take ownership of. Set routes to false from the start rather than migrating later, since the whole argument for disabling them is that gem routes can change under your URLs.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 122 days ago.
What is it written in?
Mainly Ruby, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • thoughtbot/clearance3,730 ★ · -6
Star history
Repository2026-09-242026-11-15
thoughtbot/clearance3.7k3.7k

-6 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The library ships routes and recommends you delete them

Clearance is a Rails engine for email and password authentication, tested against Rails 7.2 or newer and Ruby 3.3.11 or newer, and it installs with one Gemfile line and one generator run. What makes it interesting is the advice in the overriding section, which is to stop using its routes. As of Clearance 1.5 the recommendation is that you disable them and take full control of routing and URL design, on the reasoning that your application's URL design should not be affected if the gem's routes and URL design change later. One configuration option does it:

ruby
Clearance.configure do |config|
  config.routes = false
end

So the default is on, the recommendation is off, and the gem has a generator to dump the defaults into your application if you want a starting point. That is a coherent position for an opinionated library, but it means the shipped routes are scaffolding rather than the intended end state, and a new user has to notice the recommendation rather than infer it.

Two failure redirects default to nil and then fall back for compatibility

The redirect system is split into two lists that behave differently, and the difference is easy to miss. Five success methods redirect to `Clearance.configuration.redirect_url`, which is `/` by default: `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`. Two failure methods handle the signed-out cases, `application#url_after_denied_access_when_signed_out` and `sessions#url_after_destroy`. Both of their configuration values default to `nil`, and when left unset they fall back to `sign_in_url` for backwards compatibility. The fallback is not defined in one place: it is resolved in `sessions_controller.rb` and in `authorization.rb`, two different files, so overriding the behaviour means finding both. Each individual method can also be overridden in a subclassed controller rather than globally.

The install generator writes four things into your app

Adding the gem is `gem "clearance"` followed by bundle, and then the work happens in `rails generate clearance:install`. That generator does four separate insertions. It inserts `Clearance::User` into your `User` model and `Clearance::Controller` into your `ApplicationController`. It creates an initializer file so you can configure the defaults. And it creates a migration, with the specific behaviour that the migration either creates a users table or adds whatever columns are necessary to a table you already have, so the same generator works for a greenfield app and for one with an existing users table. Everything else is opt-in override: routes off by default as of 1.5, controllers by subclassing, views by copying them, and the layout by using your application's own.

Thirteen configuration keys and one redirect with no key

The initializer block is short and every line in it is a decision you are making rather than a value you have to supply. `allow_sign_up` and `allow_password_reset` are booleans, `cookie_name` defaults to `remember_token`, `cookie_path` to `/`, `cookie_domain` to `.example.com`, `httponly` to true, `rotate_csrf_on_sign_in` to true, `routes` to true, and `redirect_url` to `/`. Two are callables: `cookie_expiration` is a lambda receiving the cookie jar and returning a date, and `password_strategy` points at `Clearance::PasswordStrategies::BCrypt`. The remaining are the mailer sender and two failure URLs, both defaulting to nil. Note what is absent from that list: `application#url_after_denied_access_when_signed_in` appears in the redirect documentation as a method but has no configuration key in the initializer, so the signed-in and signed-out denial paths are configurable in asymmetric ways.

Access control exists at the controller layer and the routing layer

Two mechanisms, and they are not redundant. The controller one is a before_action filter:

ruby
class ArticlesController < ApplicationController
  before_action :require_login

  def index
    current_user.articles
  end
end

The routing one puts the check in the URL map instead, which means an unauthenticated request never reaches a controller at all. `Clearance::Constraints::SignedOut.new` sends anonymous visitors to one root, `SignedIn.new` sends everyone signed in to another, and `SignedIn` also accepts a block, so a check on a user attribute can be expressed at the routing level: `constraints Clearance::Constraints::SignedIn.new { |user| user.admin? }` with an admin root inside it. In views and helpers the three methods are `current_user`, `signed_in?` and `signed_out?`, and the sign-out link is a button_to with the delete method rather than a link.

cookie_domain takes a callable that receives the request

Cookie configuration is where a multi-domain deployment gets decided, and Clearance supports it by making the domain a callable rather than a string. The first argument passed to the method is an `ActionDispatch::Request`, so the domain can be derived from the request that is being served:

ruby
Clearance.configure do |config|
  config.cookie_domain = lambda { |request| request.host }
end

That replaces the fixed `.example.com` default and produces a cookie scoped to whichever host the user arrived on, which is the behaviour a set of subdomains or per-tenant domains needs. The same style is used for `cookie_expiration`, which takes the cookie jar and returns a date, defaulting to one year from now in UTC. The rest of the remember-me story is `cookie_name` as `remember_token`, `cookie_path` as `/`, `httponly` on, and `rotate_csrf_on_sign_in` on, so signing in invalidates the CSRF token as a side effect.

The Clearance session is published into the Rack environment

Clearance puts its session into the Rack environment hash under the `:clearance` key, which is what lets middleware and other Rack applications see who is signed in without knowing anything about Rails. The shape of the API follows from that placement: a middleware reads `env[:clearance].signed_in?` and then `env[:clearance].current_user`, and can act on it before calling the next app. And because the key sits in the plain environment hash, that middleware does not need to know anything about Rails at all. The example in the documentation is a small middleware class with the standard initialize and call pair that returns `current_user.bubble_gum` when signed in. This is the integration point for anything that sits in front of or beside the Rails app, including a Rack-based proxy or a custom middleware, and it means the answer to "how does my non-Rails layer know who is signed in" is already in the environment you were going to pass through.

Eight views, one generator, and two places to ask questions

Views are copied into your application rather than inherited or overridden at runtime. The list is eight paths: a mailer template for change_password, four under `passwords/`, two under `sessions/` including a form partial, and two under `users/` including a form partial. `rails generate clearance:views` copies them all into your application for editing, and the layout is your application's own by default rather than something you have to override. Support is split in a way worth knowing before you file something. Bugs go to GitHub Issues. Questions about the library go to the `clearance` tag on Stack Overflow, which is monitored by contributors. The repository itself is set up like a maintained gem: a `CODEOWNERS` file, `CONTRIBUTING.md`, `SECURITY.md`, `RELEASING.md`, an `Appraisals` file with a `gemfiles/` directory for testing against several dependency sets, `.erb_lint.yml` for the templates, `.yardopts` for the documentation, and an inch-ci badge measuring documentation coverage. The newest tag is v2.12.0, published 2026-04-17.

Editorial conclusion

Clearance fits an application that wants conventional session authentication with sensible defaults and no surprises, and it fits best if you are willing to take ownership of the parts it tells you to take ownership of. Set routes to false from the start rather than migrating later, since the whole argument for disabling them is that gem routes can change under your URLs. Change mailer_sender and cookie_domain before you go live rather than after, because both have defaults that will not suit a real deployment. If you rely on redirect behaviour, note that the two failure URLs fall back to sign_in_url in two separate files, so an override has to cover both. And take the support split at face value: bugs on the issue tracker, questions on the Stack Overflow tag.

Frequently asked questions

What are the requirements for Clearance?

Rails 7.2 or newer and Ruby 3.3.11 or newer. Add `gem "clearance"` to your Gemfile, run bundle, then run `rails generate clearance:install`. That generator inserts Clearance::User into your User model and Clearance::Controller into ApplicationController, creates an initializer file, and creates a migration that either creates a users table or adds the necessary columns to an existing one.

How do I restrict access to part of a Clearance app?

Two ways. Add a `require_login` before_action to the controller, or constrain the route: Clearance::Constraints::SignedOut.new for anonymous visitors, SignedIn.new for any signed-in user, and SignedIn.new with a block for an attribute check such as `user.admin?`. The routing layer is checked before a controller runs at all.

How do I support multiple domains with Clearance?

Set `cookie_domain` to a callable. The first argument passed to it is an ActionDispatch::Request, so `config.cookie_domain = lambda { |request| request.host }` scopes the cookie to whichever host served the request instead of a fixed `.example.com`. The same style applies to cookie_expiration, which receives the cookie jar.

How do I take over Clearance's URLs?

Set `config.routes = false`. That has been the recommendation since Clearance 1.5, so that changes to the gem's routes and URL design cannot affect your application. You can then run `rails generate clearance:routes` to dump a copy of the default routes into your own application and edit them.

Where should I ask questions about Clearance?

Bugs belong in GitHub Issues. Questions about the library belong in the `clearance` tag on Stack Overflow, which is monitored by contributors. The repository also carries CONTRIBUTING.md, SECURITY.md, RELEASING.md and a CODEOWNERS file, and its support question is deliberately not answered on the issue tracker.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. thoughtbot/clearance on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/thoughtbot-clearance.svg)](https://hysenlabs.com/projects/thoughtbot-clearance)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/thoughtbot-clearance.svg)](https://hysenlabs.com/projects/thoughtbot-clearance)

Was this useful?