Devise is a flexible authentication solution for Rails based on Warden. It:

• Is Rack based;
• Is a complete MVC solution based on Rails engines;
• Allows you to have multiple models signed in at the same time;
• Is based on a modularity concept: use only what you really need.

It's composed of 10 modules:

• Database Authenticatable: hashes and stores a password in the database to validate the authenticity of a user while signing in. The authentication can be done both through POST requests or HTTP Basic Authentication.
• Omniauthable: adds OmniAuth (https://github.com/omniauth/omniauth) support.
• Confirmable: sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.
• Recoverable: resets the user password and sends reset instructions.
• Registerable: handles signing up users through a registration process, also allowing them to edit and destroy their account.
• Rememberable: manages generating and clearing a token for remembering the user from a saved cookie.
• Trackable: tracks sign in count, timestamps and IP address.
• Timeoutable: expires sessions that have not been active in a specified period of time.
• Validatable: provides validations of email and password. It's optional and can be customized, so you're able to define your own validations.
• Lockable: locks an account after a specified number of failed sign-in attempts. Can unlock via email or after a specified time period.

Table of Contents

• Information
  • The Devise wiki
  • Bug reports
  • StackOverflow and Mailing List
  • RDocs
  • Example applications
  • Extensions
  • Supported Ruby / Rails versions
  • Contributing
• Starting with Rails?
• Getting started
  • Controller filters and helpers
  • Configuring Models
  • Strong Parameters
  • Configuring views
  • Configuring controllers
  • Configuring routes
  • I18n
  • Test helpers
  • Controller tests
  • Integration tests
  • OmniAuth
  • Configuring multiple models
  • Active Job Integration
  • Password reset tokens and Rails logs
  • Other ORMs
  • Rails API mode
• Additional information
  • Warden
• License

Information

The Devise wiki

The Devise Wiki has lots of additional information about Devise including many "how-to" articles and answers to the most frequently asked questions. Please browse the Wiki after finishing this README:

https://github.com/heartcombo/devise/wiki

Bug reports

If you discover a problem with Devise, we would like to know about it. However, we ask that you please review these guidelines before submitting a bug report:

https://github.com/heartcombo/devise/wiki/Bug-reports

If you have discovered a security related bug, please do NOT use the GitHub issue tracker. Send an email to heartcombo.oss@gmail.com.

StackOverflow and Mailing List

If you have any questions, comments, or concerns, please use StackOverflow instead of the GitHub issue tracker:

https://stackoverflow.com/questions/tagged/devise

The deprecated mailing lists can still be read on:

https://groups.google.com/group/plataformatec-devise https://groups.google.com/group/heartcombo

RDocs

You can view the Devise documentation in RDoc format here:

https://rubydoc.info/github/heartcombo/devise/main/frames

If you need to use Devise with previous versions of Rails, you can always run "gem server" from the command line after you install the gem to access the old documentation.

Example applications

There are a few example applications available on GitHub that demonstrate various features of Devise with different versions of Rails. You can view them here:

https://github.com/heartcombo/devise/wiki/Example-Applications

Extensions

Our community has created a number of extensions that add functionality above and beyond what is included with Devise. You can view a list of available extensions and add your own here:

https://github.com/heartcombo/devise/wiki/Extensions

Supported Ruby / Rails versions

We intend to maintain support for all Ruby / Rails versions that haven't reached end-of-life.

For more information about specific versions please check Ruby and Rails maintenance policies, and our test matrix.

Contributing

We hope that you will consider contributing to Devise. Please read this short overview for some information about how to get started:

https://github.com/heartcombo/devise/wiki/Contributing

You will usually want to write tests for your changes. To run the test suite, go into Devise's top-level directory and run bundle install and bin/test. Devise works with multiple Ruby and Rails versions, and ActiveRecord and Mongoid ORMs, which means you can run the test suite with some modifiers: DEVISE_ORM and BUNDLE_GEMFILE.

DEVISE_ORM

Since Devise supports both Mongoid and ActiveRecord, we rely on this variable to run specific code for each ORM. The default value of DEVISE_ORM is active_record. To run the tests for Mongoid, you can pass mongoid:

DEVISE_ORM=mongoid bin/test

==> Devise.orm = :mongoid

When running the tests for Mongoid, you will need to have a MongoDB server (version 2.0 or newer) running on your system.

Please note that the command output will show the variable value being used.

BUNDLE_GEMFILE

We can use this variable to tell bundler what Gemfile it should use (instead of the one in the current directory). Inside the gemfiles directory, we have one for each version of Rails we support. When you send us a pull request, it may happen that the test suite breaks using some of them. If that's the case, you can simulate the same environment using the BUNDLE_GEMFILE variable. For example, if the tests broke using Ruby 3.4 and Rails 8.0, you can do the following:

chruby 3.4.0 # or rbenv shell 3.4.0, or rvm use 3.4.0, etc.
BUNDLE_GEMFILE=gemfiles/Gemfile-rails-8-0 bundle install
BUNDLE_GEMFILE=gemfiles/Gemfile-rails-8-0 bin/test

You can also combine both of them if the tests broke for Mongoid:

BUNDLE_GEMFILE=gemfiles/Gemfile-rails-8-0 bundle install
BUNDLE_GEMFILE=gemfiles/Gemfile-rails-8-0 DEVISE_ORM=mongoid bin/test

Running tests

Devise uses minitest as test framework.

• Running all tests:

bin/test

• Running tests for an specific file:

bin/test test/models/trackable_test.rb

• Running a specific test given a line number or a regex:

bin/test test/models/trackable_test.rb:16
bin/test test/models/trackable_test.rb -n '/update.*record/'

Starting with Rails?

If you are building your first Rails application, we recommend you do not use Devise. Devise requires a good understanding of the Rails Framework. In such cases, we advise you to start a simple authentication system from scratch. Here's a few resources that should help you get started:

• Michael Hartl's online book: https://www.railstutorial.org/book/modeling_users
• Ryan Bates' Railscasts: http://railscasts.com/episodes/250-authentication-from-scratch and http://railscasts.com/episodes/250-authentication-from-scratch-revised
• Codecademy's Ruby on Rails: Authentication and Authorization: https://www.codecademy.com/learn/rails-auth

Once you have solidified your understanding of Rails and authentication mechanisms, we assure you Devise will be very pleasant to work with. :smiley:

Getting started

Devise 5 works with Rails 7 onwards. Run:

bundle add devise

Next, you need to run the generator:

rails generate devise:install

At this point, a number of instructions will appear in the console. Among these instructions, you'll need to set up the default URL options for the Devise mailer in each environment. Here is a possible configuration for config/environments/development.rb:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

The generator will install an initializer which describes ALL of Devise's configuration options. It is imperative that you take a look at it. When you are done, you are ready to add Devise to any of your models using the generator.

In the following command you will replace MODEL with the class name used for the application’s users (it’s frequently User but could also be Admin). This will create a model (if one does not exist) and configure it with the default Devise modules. The generator also configures your config/routes.rb file to point to the Devise controller.

rails generate devise MODEL

Next, check the MODEL for any additional configuration options you might want to add, such as confirmable or lockable. If you add an option, be sure to inspect the migration file (created by the generator if your ORM supports them) and uncomment the appropriate section. For example, if you add the confirmable option in the model, you'll need to uncomment the Confirmable section in the migration.

Then run rails db:migrate

You should restart your application after changing Devise's configuration options (this includes stopping spring). Otherwise, you will run into strange errors, for example, users being unable to login and route helpers being undefined.

Controller filters and helpers

Devise will create some helpers to use inside your controllers and views. To set up a controller w