How To: Allow Users To Sign In Using Their Username Or Email Address

For this example, we will assume your model is called User.

Create a username field in the `users` table

Create a migration:

rails generate migration add_username_to_users username:string:uniq

Run the migration:

rake db:migrate

Strong parameters

Modify application_controller.rb and add username, email, password, password confirmation and remember me to configure_permitted_parameters

ruby

class ApplicationController < ActionController::Base
  before_action :configure_permitted_parameters, if: :devise_controller?

  protected

  def configure_permitted_parameters
    added_attrs = [:username, :email, :password, :password_confirmation, :remember_me]
    devise_parameter_sanitizer.permit :sign_up, keys: added_attrs
    devise_parameter_sanitizer.permit :sign_in, keys: [:login, :password]
    devise_parameter_sanitizer.permit :account_update, keys: added_attrs
  end
end

see also "strong parameters"

Create a login virtual attribute in the `User` model

Add login as an User:

ruby

# app/models/user.rb

  attr_writer :login

  def login
    @login || self.username || self.email
  end

Tell Devise to use `:login` in the `authentication_keys`

Modify config/initializers/devise.rb to have:

ruby

config.authentication_keys = [ :login ]

If you are using multiple models with Devise, it is best to set the authentication_keys on the model itself if the keys may differ:

ruby

  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :trackable, 
         :validatable, authentication_keys: [:login]

If you need permissions, you should implement that in a before filter. You can also supply a hash where the value is a boolean determining whether or not authentication should be aborted when the value is not present.

ruby

  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :trackable, 
         :validatable, :authentication_keys => {email: true, login: false}

Overwrite Devise's `find_for_database_authentication` method in `User` model

Because we want to change the behavior of the login action, we have to overwrite the find_for_database_authentication method. The method's stack works like this: find_for_database_authentication calls find_for_authentication which calls find_first_by_auth_conditions. Overriding the find_for_database_authentication method allows you to edit database authentication; overriding find_for_authentication allows you to redefine authentication at a specific point (such as token, LDAP or database). Finally, if you override the find_first_by_auth_conditions method, you can customize finder methods (such as authentication, account unlocking or password recovery).

For ActiveRecord:

MySQL users: the use of the SQL lower function below is most likely unnecessary and will cause any index on the email column to be ignored.

ruby

# app/models/user.rb

    def self.find_for_database_authentication(warden_conditions)
      conditions = warden_conditions.dup
      if (login = conditions.delete(:login))
        where(conditions.to_h).where(["lower(username) = :value OR lower(email) = :value", { :value => login.downcase }]).first
      elsif conditions.has_key?(:username) || conditions.has_key?(:email)
        where(conditions.to_h).first
      end
    end

If Rails4: use to_hash instead; or the to_h would be empty hash because by default no permitted params are set in passwords_controller.rb.

And if you want email to be case insensitive, you should add

ruby

conditions[:email].downcase! if conditions[:email]
where(conditions.to_h).first

Be sure to add case insensitivity to your validations on :username:

ruby

# app/models/user.rb

  validates :username, presence: true, uniqueness: { case_sensitive: false }

Alternatively, change the find conditions like so:

ruby

# when allowing distinct User records with, e.g., "username" and "UserName"...
where(conditions).where(["username = :value OR lower(email) = lower(:value)", { :value => login }]).first

However, we need to be very careful with username validation, because there might be conflict between username and email. For example, given these users:

id	username	email
1	harrypotter	[email protected]
2	[email protected]	[email protected]

The problem is at user #2, he is using #1's email as his username. What would happen if #1 try to log in by his email [email protected]? With the above query:

ruby

where(conditions).where(["username = :value OR lower(email) = lower(:value)", { :value => login }]).first

User #1 (harrypotter) will never be able to log in to the system, because that query always return #2.

To fix it, we can add one more validation to check format of username to not allow @ character:

ruby

# app/models/user.rb

  # only allow letter, number, underscore and punctuation.
  validates_format_of :username, with: /^[a-zA-Z0-9_\.]*$/, :multiline => true

You could also check if the same email as the username already exists in the database:

ruby

# app/models/user.rb

validate :validate_username

def validate_username
  if User.where(email: username).exists?
    errors.add(:username, :invalid)
  end
end

However, note that relying ONLY on this second validation still allows a user to choose someone else's valid email address as a username, as long as that email is not yet associated with an account. This should therefore be used only as a backup validation.

For Mongoid:

Note: This code for Mongoid does some small things differently than the ActiveRecord code above. Would be great if someone could port the complete functionality of the ActiveRecord code over to Mongoid [basically you need to port the 'where(conditions)']. It is not required but will allow greater flexibility.

ruby

  field :email

  def self.find_first_by_auth_conditions(warden_conditions)
    conditions = warden_conditions.dup
    if (login = conditions.delete(:login))
      self.any_of({ :username =>  /^#{Regexp.escape(login)}$/i }, { :email =>  /^#{Regexp.escape(login)}$/i }).first
    else
      super
    end
  end

The code below also supports Mongoid but uses the where method and the OR operator to choose between username and email.

ruby

  # function to handle user's login via email or username
  def self.find_for_database_authentication(warden_conditions)
    conditions = warden_conditions.dup
    if (login = conditions.delete(:login).downcase)
      where(conditions).where('$or' => [ {:username => /^#{Regexp.escape(login)}$/i}, {:email => /^#{Regexp.escape(login)}$/i} ]).first
    else
      where(conditions).first
    end
  end

Update your views

Make sure you have the Devise views in your project so that you can customize them

rails g devise:views

rails g devise:views users

in case you have multiple models and you want customized views.

Simply modify config/initializers/devise.rb file to have:

ruby

config.scoped_views = true

Rails 2:

script/generate devise_views

Modify the views

sessions/new.html.erb:

diff

-  <p><%= f.label :email %>

-  <%= f.email_field :email %></p>
+  <p><%= f.label :login %>

+  <%= f.text_field :login %></p>

Use :login and not :username in the sessions/new.html.erb

registrations/new.html.erb:

diff

+  <p><%= f.label :username %>

+  <%= f.text_field :username %></p>
  <p><%= f.label :email %>

  <%= f.email_field :email %></p>

registrations/edit.html.erb:

diff

+  <p><%= f.label :username %>

+  <%= f.text_field :username %></p>
  <p><%= f.label :email %>

  <%= f.email_field :email %></p>

Newer versions have different HTML.

Allow users to recover their password or confirm their account using their username

This section assumes you have run through the steps in Allow users to Sign In using their username or email.

Configure Devise to use username as reset password or confirmation keys

Simply modify config/initializers/devise.rb to have:

ruby

config.reset_password_keys = [ :username ]
config.confirmation_keys = [ :username ]

Use `find_first_by_auth_conditions` instead of `find_for_database_authentication`

Replace (in your User.rb):

ruby

def self.find_for_database_authentication(warden_conditions)
  conditions = warden_conditions.dup
  if (login = conditions.delete(:login))
    where(conditions).where(["lower(username) = :value OR lower(email) = :value", { :value => login.downcase }]).first
  else
    where(conditions).first
  end
end

with:

ruby

def self.find_first_by_auth_conditions(warden_conditions)
  conditions = warden_conditions.dup
  if (login = conditions.delete(:login))
    where(conditions).where(["lower(username) = :value OR lower(email) = :value", { :value => login.downcase }]).first
  else
    if conditions[:username].nil?
      where(conditions).first
    else
      where(username: conditions[:username]).first
    end
  end
end

Update your views

passwords/new.html.erb:

diff

-  <p><%= f.label :email %>

-  <%= f.email_field :email %></p>
+  <p><%= f.label :username %>

+  <%= f.text_field :username %></p>

confirmations/new.html.erb:

diff

-  <p><%= f.label :email %>

-  <%= f.email_field :email %></p>
+  <p><%= f.label :username %>

+  <%= f.text_field :username %></p>

Gmail or me.com Style

Another way to do this is me.com and gmail style. You allow an email or the username of the email. For public facing accounts, this has more security. Rather than allow some hacker to enter a username and then just guess the password, they would have no clue what the user's email is. Just to make it easier on the user for logging in, allow a short form of their email to be used e.g "[email protected]" or just "someone" for short.

ruby

  after_initialize :create_login, :if => :new_record?

  def create_login
    if self.username.blank?
      email = self.email.split(/@/)
      login_taken = Pro.where(:username => email[0]).first
      unless login_taken
        self.username = email[0]
      else    
        self.username = self.email
      end   
    end     
  end

  # You might want to use the self.find_first_by_auth_conditions(warden_conditions) above
  # instead of using this find_for_database_authentication as this one causes problems.
  # def self.find_for_database_authentication(conditions)
  #   where(:username => conditions[:email]).first || where(:email => conditions[:email]).first
  # end

Allow users to Sign In using their username or email address

Create a username field in the users table

Create a migration:

Run the migration:

Strong parameters

Create a login virtual attribute in the User model

Tell Devise to use :login in the authentication_keys

Overwrite Devise's find_for_database_authentication method in User model

For ActiveRecord:

For Mongoid:

Update your views

Modify the views

Allow users to recover their password or confirm their account using their username

Configure Devise to use username as reset password or confirmation keys

Use find_first_by_auth_conditions instead of find_for_database_authentication

Update your views

Gmail or me.com Style

Create a username field in the `users` table

Create a login virtual attribute in the `User` model

Tell Devise to use `:login` in the `authentication_keys`

Overwrite Devise's `find_for_database_authentication` method in `User` model

Use `find_first_by_auth_conditions` instead of `find_for_database_authentication`