What is clearance?

Clearance is a Ruby gem that adds email-and-password authentication to Ruby on Rails applications. It is built by thoughtbot and designed to be small, well-tested, and straightforward to install. The gem supports Rails 7.2 and above, and Ruby 3.3.11 and above. To get started, you add the gem to your project, run the bundler, and then run a generator command. The generator does several things: it mixes authentication behavior into your User model, sets up your ApplicationController to know about sessions, creates a configuration initializer file, and generates a database migration that either creates a users table or adds the needed columns to one you already have. Once installed, you can protect any controller action by adding a before-action filter that checks whether the user is signed in. Clearance also provides routing constraints so you can decide which parts of your site signed-in users, signed-out users, or admins can reach, all from the routes file. In views and controllers you get three helper methods: one to get the current user, one to check whether someone is signed in, and one to check whether they are signed out. Password resets are built in. When a user requests a reset, Clearance sends them an email. You configure the sender address in the initializer file. The gem also supports multiple domains and can expose its session data to Rack middleware, so other parts of the application stack can interact with the authentication state. Most parts of Clearance can be replaced or adjusted. Routes can be disabled so you define your own URL design. Controllers can be subclassed to change specific behaviors. Views can be copied into your app for editing, and layouts per controller can be set in your application config. Flash messages and email subject lines live in translation files and can be overridden like any other string in a Rails project.