Monban is designed to be a very simple and extensible user authentication library for rails. Its goal is to give all the power to the developer instead of forcing them to make Monban work with their system.
Why use Monban?
Monban makes authentication simple:
- Easy to use in tests with dependency injection
- Provides convenient controller helpers
- Very customizable
Monban doesn't do the following:
- Doesn't automatically add routes to your application
- Doesn't force you to use engine based controllers or views
- Doesn't require you to make changes to your user model
You can read the full documentation at rubydoc
Monban was designed to work with Rails > 4.0. Add this line to your Gemfile:
Then inside of your ApplicationController add the following:
And you're ready to start designing your authentication system.
If you'd like a good starting point for building an app using Monban, it is suggested to use the monban generators
Monban does currently have some out-of-the-box expectations, but you can configure and change any of these:
- By default the model should be called
- Monban expects your user model to respond to
- You should have an
password_digestcolumn on your
- Passwords will be handled with BCrypt
Monban provides the following controller methods:
And this filter:
Usage in Tests
Monban provides the following:
Which will change password hashing method to provide plaintext responses instead of using BCrypt. This will allow you to write factories using the password_digest field:
FactoryGirl.define do factory :user do username 'wombat' password_digest 'password' end end
A couple of convenience methods are available in your tests.
Monban.test_mode! RSpec.configure do |config| config.include Monban::Test::Helpers, type: :feature config.after :each do Monban.test_reset! end end
feature "A feature spec" do scenario "that requires login" do user = create(:user) sign_in(user) # do something sign_out # do something else end end
Similar to clearance's backdoor you can visit a path and sign in quickly via
user = create(:user) visit dashboard_path(as: user)
To enable this functionality you'll want to add the following to
config.middleware.insert_after Warden::Manager, Monban::BackDoor
If you are going to write controller tests, helpers are provided for those as well:
Monban.test_mode! RSpec.configure do |config| config.include Monban::Test::ControllerHelpers, type: :controller config.after :each do Monban.test_reset! end end
require 'spec_helper' describe ProtectedController do describe "GET 'index'" do it "returns http success when signed in" do user = create(:user) sign_in(user) get 'index' response.should be_success end it "redirects when not signed in" do get 'index' response.should be_redirect end end end
Authentication with username instead of email
If you want to sign in with username instead of email just change the configuration option
# config/initializers/monban.rb Monban.configure do |config| config.user_lookup_field = :username end
If you used the monban:scaffold generator from monban generators you'll have to change the following four references to email.
- In SessionsController#session_params
- In UsersController#user_params
- The email form field on sessions#new
- The email form field on users#new
Using multiple lookup fields
You may perform a look up on a user using multiple fields by doing something like the following:
class SessionsController < ApplicationController def create user = authenticate_session(session_params, email_or_username: [:email, :username]) if sign_in(user) redirect_to(root_path) else render :new end end private def session_params params.require(:session).permit(:email_or_username, :password) end end
This will allow the user to enter either their username or email to login
Monban::Configuration has lots of options for changing how monban works. Currently the options you can change are as follows:
- user_lookup_field: (default
- user_token_field: (default
:password) Field the form submits containing the undigested password.
- user_token_store_field: (default:
:password_digest) Field in the database that stores the user's digested password.
- user_class: (default:
User) The user class.
- sign_in_notice: (default:
You must be signed in) Rails flash message to set when user signs in.
- sign_in_service: (default:
Monban::Services::SignIn) Service for signing a user in.
- sign_up_service: (default:
Monban::Services::SignUp) Service for signing a user up.
- sign_out_service: (default:
Monban::Services::SignOut) Service for signing a user out.
- authentication_service: (default:
Monban::Services::Authentication) Service for authenticated a user.
- password_reset_service: (default:
Monban::Services::PasswordReset) Service for resetting a user's password.
- no_login_handler: A before_action for rails that handles when a user is not signed in.
- no_login_redirect: Used by the no_login_handler to redirect the user
- hashing_method: Method to hash an undigested password.
- token_comparison: Method to compare a digested and undigested password.
- creation_method: Method for creating a user.
- find_method: Method for finding a user.
- failure_app: Necessary for warden to work. A rack app that handles failures in authentication.
Here are a few of the current limitations of monban:
- Monban assumes you only have one user model.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request