Clearance: Rails Authentication Made Easy

Clearance is a great solution for email and password authentication. It can handle other types of authentication, but it's really meant for email/password. Just like Rails, Clearance is opinionated, and those opinions help make it more secure and easier to use.

Some non-Clearance authentication libraries

What does has_secure_password do?

has_secure_password is the "low end": it worries about persisting something securely to the database. It uses the secure BCrypt algorithm to hash a password and store that hash in the database. It's a great start for rolling a custom authentication solution, because it means you don't need to (and should not) write your own cryptography. You do have to build controllers and forms on top of that, though, and those are often repetitive. Clearance can help with that.

What does Devise do?

Devise can do anything, including forcing people to confirm email after registering or use multiple models (User, Account) to sign in. Devise does more, but is less opinionated than Clearance, because Devise can be bent in any direction. Clearance has a clear point of view about the best way to sign up and sign in.

A quick overview of Clearance's differences

Like Devise, Clearance has built-in controllers and views for a quick drop-in setup. Clearance can also generate those files into your Rails app so you can customize them, or override them entirely. It hooks into Rails' I18n API to change field labels and flash messages, so those can be customized without changing or overriding any views.

Installation

The Clearance README is comprehensive and has received a lot of attention over the past year. It's a great resource for learning how to install and use Clearance.

Let's look at how to install Clearance on a quick_blog app (which was created by running rails new then rails generate scaffold post).

1. Add clearance and rspec-rails to the Gemfile
2. rails generate clearance:install will create a Clearance initializer, where we can change some settings, insert Clearance code into the ApplicationController, and generate a User model for us if we don't have one. If there is a User model, Clearance will only add the fields it needs.
3. Next, we set the action_mailer.default_url_options for Clearance. This will make reading and using links in local emails much easier.
4. Clearance makes heavy use of flashes, so it provides some sample code for showing flashes to the user.
5. Finally, we run rake db:migrate.

Now that Clearance is set up, there's a "Sign in" link on pages, which we can click on, then sign up, sign in, sign out, and it all Just Works.

Testing Clearance

Clearance has great integration with RSpec:

rails generate clearance:specs

That command generates Factory Girl factories, feature specs for signing in/out/up, and some helpful files in spec/support/.

After running the command above, we can run bundle exec rspec and watch all of the tests pass. These specs work with Clearance out of the box, and can be easily changed if you customize Clearance.

Customizing Routes

Derek likes to dump all of Clearance's routes into config/routes.rb so he can see what routes are available and remove unused routes. Here's how to do that:

rails generate clearance:routes

That will insert Clearance's default routes into the routes file, ready to be edited. It will also change the Clearance configuration in config/initializers/clearance.rb to tell Clearance not to use its built-in routes and instead use the routes you just generated.

Routing Constraints

Routing constraints are a feature in Clearance that lets you hide entire routes depending on a user's state. For example, if you want to hide the /admin route if a user isn't an admin:

constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
  get "/admin" => "admin/dashboards#show"
end

When someone who is signed out, or signed in as a non-admin, they will get a 404 when they try to visit /admin. The route doesn't even exist for them.

Looking ahead

Clearance has been around a long time (since 2009!). That 2009-era legacy means that it's not as secure as it could be. Fortunately, Clearance version 2.0 is coming out soon, which will have some (breaking) changes that will improve security even more. The 1.x branch will still support Rails 5.

Wrapping up

Clearance is a great, featureful, opinionated framework for email and password authentication. Derek has been working very hard on documentation, so the documentation is comprehensive and each class and module (like Clearance::PasswordStrategies has documentation that explains its purpose.