Technology moves fast! ⚑ Don't get left behind.🚢 Subscribe to our mailing list to keep up with latest and greatest in open source projects! πŸ†


Subscribe to our mailing list

clearance

Rails authentication with email & password.

Subscribe to updates I use clearance


Statistics on clearance

Number of watchers on Github 2832
Number of open issues 34
Average time to close an issue 11 days
Main language Ruby
Average time to merge a PR 5 days
Open pull requests 38+
Closed pull requests 26+
Last commit over 1 year ago
Repo Created over 10 years ago
Repo Last Updated over 1 year ago
Size 6.26 MB
Homepage https://thoughtbo...
Organization / Authorthoughtbot
Latest Releasev1.16.1
Contributors95
Page Updated
Do you use clearance? Leave a review!
View open issues (34)
View clearance activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating clearance for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Clearance

Build Status Code Climate Documentation Quality

Rails authentication with email & password.

Clearance is intended to be small, simple, and well-tested. It has opinionated defaults but is intended to be easy to override.

Please use GitHub Issues to report bugs. If you have a question about the library, please use the clearance tag on Stack Overflow. This tag is monitored by contributors.

Getting Started

Clearance is a Rails engine tested against Rails >= 3.2 and Ruby >= 1.9.3.

You can add it to your Gemfile with:

gem "clearance"

Run the bundle command to install it.

After you install Clearance, you need to run the generator:

$ rails generate clearance:install

The Clearance install generator:

  • Inserts Clearance::User into your User model
  • Inserts Clearance::Controller into your ApplicationController
  • Creates an initializer file to allow further configuration.
  • Creates a migration file that either create a users table or adds any necessary columns to the existing table.

Configure

Override any of these defaults in config/initializers/clearance.rb:

Clearance.configure do |config|
  config.allow_sign_up = true
  config.cookie_domain = ".example.com"
  config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
  config.cookie_name = "remember_token"
  config.cookie_path = "/"
  config.routes = true
  config.httponly = false
  config.mailer_sender = "reply@example.com"
  config.password_strategy = Clearance::PasswordStrategies::BCrypt
  config.redirect_url = "/"
  config.rotate_csrf_on_sign_in = false
  config.secure_cookie = false
  config.sign_in_guards = []
  config.user_model = User
end

The install generator will set rotate_csrf_on_sign_in to true, so new installations will get this behavior from the start. This helps avoid session fixation attacks, and will become the default in Clearance 2.0.

Use

Access Control

Use the require_login filter to control access to controller actions.

class ArticlesController < ApplicationController
  before_action :require_login

  def index
    current_user.articles
  end
end

Clearance also provides routing constraints that can be used to control access at the routing layer:

Blog::Application.routes.draw do
  constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
    root to: "admin/dashboards#show", as: :admin_root
  end

  constraints Clearance::Constraints::SignedIn.new do
    root to: "dashboards#show", as: :signed_in_root
  end

  constraints Clearance::Constraints::SignedOut.new do
    root to: "marketing#index"
  end
end

Helper Methods

Use current_user, signed_in?, and signed_out? in controllers, views, and helpers. For example:

<% if signed_in? %>
  <%= current_user.email %>
  <%= button_to "Sign out", sign_out_path, method: :delete %>
<% else %>
  <%= link_to "Sign in", sign_in_path %>
<% end %>

Password Resets

When a user resets their password, Clearance delivers them an email. You should change the mailer_sender default, used in the email's from header:

Clearance.configure do |config|
  config.mailer_sender = "reply@example.com"
end

Integrating with Rack Applications

Clearance adds its session to the Rack environment hash so middleware and other Rack applications can interact with it:

class Bubblegum::Middleware
  def initialize(app)
    @app = app
  end

  def call(env)
    if env[:clearance].signed_in?
      env[:clearance].current_user.bubble_gum
    end

    @app.call(env)
  end
end

Overriding Clearance

Routes

See config/routes.rb for the default set of routes.

As of Clearance 1.5 it is recommended that you disable Clearance routes and take full control over routing and URL design. This ensures that your app's URL design won't be affected if the gem's routes and URL design are changed.

To disable the routes, set config.routes = false. You can optionally run rails generate clearance:routes to dump a copy of the default routes into your application for modification.

Controllers

See app/controllers/clearance for the default behavior. Many protected methods were extracted in these controllers in an attempt to make overrides and hooks simpler.

To override a Clearance controller, subclass it and update the routes to point to your new controller (see the Routes section).

class PasswordsController < Clearance::PasswordsController
class SessionsController < Clearance::SessionsController
class UsersController < Clearance::UsersController

Redirects

All of these controller 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
application#url_after_denied_access_when_signed_in

To override them all at once, change the global configuration of redirect_url. To change individual URLs, override the appropriate method.

application#url_after_denied_access_when_signed_out defaults to sign_in_url. Override this method to change this.

Views

See app/views for the default behavior.

To override a view, create your own copy of it:

app/views/clearance_mailer/change_password.html.erb
app/views/passwords/create.html.erb
app/views/passwords/edit.html.erb
app/views/passwords/new.html.erb
app/views/sessions/_form.html.erb
app/views/sessions/new.html.erb
app/views/users/_form.html.erb
app/views/users/new.html.erb

You can use the Clearance views generator to copy the default views to your application for modification.

$ rails generate clearance:views

Layouts

By default, Clearance uses your application's default layout. If you would like to change the layout that Clearance uses when rendering its views, simply specify the layout in the config/application.rb

config.to_prepare do
  Clearance::PasswordsController.layout "my_passwords_layout"
  Clearance::SessionsController.layout "my_sessions_layout"
  Clearance::UsersController.layout "my_admin_layout"
end

Translations

All flash messages and email subject lines are stored in i18n translations. Override them like any other translation.

See config/locales/clearance.en.yml for the default behavior.

You can also install clearance-i18n for access to additional, user-contributed translations.

User Model

See lib/clearance/user.rb for the default behavior. You can override those methods as needed.

Deliver Email in Background Job

Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance 1.6 or greater, Clearance will use ActiveJob's deliver_later method to automatically take advantage of your configured queue.

If you are using an earlier version of Rails, you can override the Clearance::Passwords controller and define the behavior you need in the deliver_email method.

class PasswordsController < Clearance::PasswordsController
  def deliver_email(user)
    ClearanceMailer.delay.change_password(user)
  end
end

Extending Sign In

By default, Clearance will sign in any user with valid credentials. If you need to support additional checks during the sign in process then you can use the SignInGuard stack. For example, using the SignInGuard stack, you could prevent suspended users from signing in, or require that users confirm their email address before accessing the site.

SignInGuards offer fine-grained control over the process of signing in a user. Each guard is run in order and hands the session off to the next guard in the stack.

A SignInGuard is an object that responds to call. It is initialized with a session and the current stack.

On success, a guard should call the next guard or return SuccessStatus.new if you don't want any subsequent guards to run.

On failure, a guard should call FailureStatus.new(failure_message). It can provide a message explaining the failure.

For convenience, a SignInGuard class has been provided and can be inherited from. The convenience class provides a few methods to help make writing guards simple: success, failure, next_guard, signed_in?, and current_user.

Here's an example custom guard to handle email confirmation:

Clearance.configure do |config|
  config.sign_in_guards = [EmailConfirmationGuard]
end
class EmailConfirmationGuard < Clearance::SignInGuard
  def call
    if unconfirmed?
      failure("You must confirm your email address.")
    else
      next_guard
    end
  end

  def unconfirmed?
    signed_in? && !current_user.confirmed_at
  end
end

Testing

Fast Feature Specs

Clearance includes middleware that avoids wasting time spent visiting, loading, and submitting the sign in form. It instead signs in the designated user directly. The speed increase can be substantial.

Enable the Middleware in Test:

# config/environments/test.rb
MyRailsApp::Application.configure do
  # ...
  config.middleware.use Clearance::BackDoor
  # ...
end

Usage:

visit root_path(as: user)

Additionally, if User#to_param is overridden, you can pass a block in order to override the default behavior:

# config/environments/test.rb
MyRailsApp::Application.configure do
  # ...
  config.middleware.use Clearance::BackDoor do |username|
    Clearance.configuration.user_model.find_by(username: username)
  end
  # ...
end

Ready Made Feature Specs

If you're using RSpec, you can generate feature specs to help prevent regressions in Clearance's integration with your Rails app over time. These feature specs, will also require factory_bot_rails.

To Generate the clearance specs, run:

$ rails generate clearance:specs

Controller Test Helpers

To test controller actions that are protected by before_action :require_login, require Clearance's test helpers in your test suite.

For rspec, add the following line to your spec/rails_helper.rb or spec/spec_helper if rails_helper does not exist:

require "clearance/rspec"

For test-unit, add this line to your test/test_helper.rb:

require "clearance/test_unit"

This will make Clearance::Controller methods work in your controllers during functional tests and provide access to helper methods like:

sign_in
sign_in_as(user)
sign_out

View and Helper Spec Helpers

Does the view or helper you're testing reference signed_in?, signed_out? or current_user? If you require 'clearance/rspec', you will have the following helpers available in your view specs:

sign_in
sign_in_as(user)

These will make the clearance view helpers work as expected by signing in either a new instance of your user model (sign_in) or the object you pass to sign_in_as. If you do not call one of these sign in helpers or otherwise set current_user in your view specs, your view will behave as if there is no current user: signed_in? will be false and signed_out? will be true.

Contributing

Please see CONTRIBUTING.md. Thank you, contributors!

License

Clearance is copyright 2009-2018 thoughtbot. It is free software, and may be redistributed under the terms specified in the LICENSE file.

About thoughtbot

thoughtbot

Clearance is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See our other projects or hire us to design, develop, and grow your product.

clearance open issues Ask a question     (View All Issues)
  • over 2 years Reset password does not deliver_later
  • over 2 years undefined method `[]' for nil:NilClass in Clearance::PasswordsController
  • over 2 years different behavior for api calls
  • over 2 years config.allow_sign_up = false - still allows sign_up?
  • over 2 years recipe for api authentication?
  • almost 3 years Q: post-sign_in hook
  • almost 3 years rails d clearance:views deletes application.html.erb
  • almost 3 years Git repo has warnings and errors
  • almost 3 years Test helpers don't exist on Rails 5 Minitest integration tests
  • almost 3 years When a user refreshes the page, "if signed_in?" shows the user they are not signed
  • about 3 years Per-device remember tokens
  • over 3 years Make user enumeration by timing attacks more difficult
  • over 3 years Duplicate cookie sent when using cookie domains
  • over 3 years Should we store a digest of confirmation_token?
  • over 3 years Validate email address is entered for passwords#create
  • about 4 years No validation messages for sign up
  • over 4 years Offer different user_params method for users#create and users#new
  • almost 5 years Expire password reset token after a period of time
  • over 5 years Don't validate user when updating password
clearance open pull requests (View All Pulls)
  • Add spanish i18n
  • Fix for duplicate cookie when using cookie domain option
  • Set an expiration for password reset tokens
  • Allow vendorizing of gems
  • Add Defer Sign In Password Check feature
  • Remove html in text version of change password
  • Allow Clearance::BackDoor to take a block
  • Use config.redirect_url in deny_access matcher
  • Inject `include Clearance::User` inside model body
  • Add expiring, databaseless password reset tokens
  • Update README.md
  • Fix incompatibility with the attr encrypted gem
  • remove unnecessary return from lib/clearance/user.rb
  • additional info about disabling Clearance default routes
  • Do not generate application layout file
  • notes on how to put forms into other views
  • Compliance with thoughtbot’s Ruby style guide
  • Cleanup `Clearance::PasswordsController#new` spec
  • Remove unused nested `create` routes
  • Reset CSRF token on sign in
  • Remove users/password#create route
  • Use standard paths for views and translations
  • Unique constraints for tokens
  • Avoid NoMethodError when receiving invalid params
  • Follow best practices for version comparison
  • Fix link in README
  • write a single cookie with the correct options
  • Do not depend on Rails
  • Add indexes to unique columns
  • Updates to use `scope` and to use `to:` in routing generator template
  • Return authentication cookie only if authentication is performed
  • Proposal: Making [ActionMailer::Base] an optional dependancy
  • Remove unused method PasswordsController#url_after_create
  • remove rails dependency
  • Vagrant
  • Rails 5.1 support
  • added missing translation keys
  • Update Nokogiri development dependency
clearance questions on Stackoverflow (View All Questions)
  • creating user authentication with clearance
  • Clearance additional strong_parameters in RoR4
  • how to automate the back out queue clearance in WMQ?
  • Tiny clearance regarding Consumer-Producer/Bounded Buffer
  • needs clearance for file conflicts
  • Javascript loop for pathfinding clearance
  • Is clearance of output caching clear all caching?
  • Multi model sign up with clearance in Rails 4
  • Troubles when reading clearance source code
  • Magento - overlay a 'clearance' icon on all products in clearance category
  • Clearance: change user password
  • rails 4 and thoughtbot/clearance - adding fields to the user model
  • Need some clearance on how to write this program
  • Authentication with Neo4j: Is Ruby's Devise or Clearance gems compatible with neography?
  • Use an Authorized Password to allow sign-up with Clearance
  • Batch file with "access clearance"
  • Clearance Gem creating user login password in encrypted format
  • Clearance while creating a sandbox user in salesforce
  • Radio button drop down pop up window fee clearance
  • Radio button Fee Clearance
  • Radio button clearance
  • Using Clearance with API
  • Overriding routes in the Clearance gem
  • Clearance undefined method sign_in for nil:NilClass
  • Margin collapse and clearance
  • Content Security Policy: If set, cannot load script from bookmarklet. Is a browser extension granted clearance?
  • Using fixtures with Clearance in Rails 4 for unit test user model
  • Rails 4 with Clearance password reset issue
  • Can't log in to existing Clearance accounts after upgrading from Rails 2.3 to 4.1
  • How to zoom an image and keep its clearance?
clearance list of languages used
clearance latest release notes
v1.16.1 v1.16.1

Fixed

  • Fixed issue where tokens from abandoned password reset attempts were stored in the session, preventing newly generated password reset tokens from working.
  • Improve compatibility with Rails API projects by calling helper_method only when it is defined.
  • URL fragment in server-set session[:return_to] values are preserved when redirecting to the stored value.
  • Eliminated deprecation in Clearance test helpers that were related to the renaming of FactoryGirl to FactoryBot.

full changelog

v1.16.0 v1.16.0

Security

  • Clearance users can now help prevent session fixation attacks by setting Clearance.configuration.rotate_csrf_on_sign_in to true. This will cause the user's CSRF token to be rotated on sign in and is recommended for all Clearance applications. This setting will default to true in Clearance 2.0. Clearance will emit a warning on each sign in until this configuration setting is explicitly set to true or false.

Full changelog

v1.15.1

Fixed

  • Password reset form redirect no longer uses a named route helper, which means it will work for developers that have customized their routes.

Full Changelog

Other projects in Ruby