Skip to content

snapshot/devise

BranchesTags
 
 

Repository files navigation

Devise ↑

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 roles (or models/scopes) signed in at the same time;

  • Is based on a modularity concept: use just what you really need.

It’s comprised of 12 modules:

  • Database Authenticatable: encrypts 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.

  • Token Authenticatable: signs in a user based on an authentication token (also known as “single access token”). The token can be given both through query string or HTTP Basic Authentication.

  • Omniauthable: adds Omniauth (github.com/intridea/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 no activity 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.

  • Encryptable: adds support of other authentication mechanisms besides the built-in Bcrypt (the default).

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:

wiki.github.com/plataformatec/devise

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:

github.com/plataformatec/devise/wiki/Bug-reports

If you found a security bug, do NOT use the GitHub issue tracker. Send email or a private GitHub message to the maintainers listed at the bottom of the README.

Mailing list ↑

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

groups.google.com/group/plataformatec-devise

RDocs ↑

You can view the Devise documentation in RDoc format here:

rubydoc.info/github/plataformatec/devise/master/frames

If you need to use Devise with Rails 2.3, 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:

github.com/plataformatec/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:

github.com/plataformatec/devise/wiki/Extensions

Contributing ↑

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

github.com/plataformatec/devise/wiki/Contributing

You will usually want to write tests for your changes. To run the test suite, ‘cd` into Devise’s top-level directory and run ‘bundle install` and `rake`. For the tests to pass, you will need to have a MongoDB server (version 1.6 or newer) running on your system.

Installation ↑

You can use the latest Rails 3 gem with the latest Devise gem:

gem install devise

After you install Devise and add it to your Gemfile, you need to run the generator:

rails generate devise:install

The generator will install an initializer which describes ALL Devise’s configuration options and you MUST take a look at it. When you are done, you are ready to add Devise to any of your models using the generator:

rails generate devise MODEL

Replace MODEL by the class name used for the applications users, it’s frequently ‘User’ but could also be ‘Admin’. This will create a model (if one does not exist) and configure it with default Devise modules. Next, you’ll usually run db:migrate as the generator will have created a migration file (if your ORM supports them). This generator also configures your config/routes.rb file, continue reading this file to understand exactly what the generator produces and how to use it.

Support for Rails 2.3.x can be found by installing Devise 1.0.x from the v1.0 branch.

Starting with Rails? ↑

If you are building your first Rails application, we recommend you to 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, today we have two resources:

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

Getting started ↑

This is a walkthrough with all steps you need to setup a devise resource, including model, migration, route files, and optional configuration.

Devise must be set up within the model (or models) you want to use. Devise routes must be created inside your config/routes.rb file.

We’re assuming here you want a User model with some Devise modules, as outlined below:

class User < ActiveRecord::Base
  devise :database_authenticatable, :registerable, :confirmable, :recoverable, :rememberable, :trackable, :validatable
end

After you choose which modules to use, you need to set up your migrations. Luckily, Devise has some helpers to save you from this boring work:

create_table :users do |t|
  t.database_authenticatable
  t.confirmable
  t.recoverable
  t.rememberable
  t.trackable
  t.timestamps
end

Devise doesn’t use attr_accessible or attr_protected inside its modules, so be sure to define attributes as accessible or protected in your model.

Configure your routes after setting up your model. Open your config/routes.rb file and add:

devise_for :users

This will use your User model to create a set of needed routes (you can see them by running ‘rake routes`). If you invoked the devise generator, you noticed that this is exactly what the generator produces for us: model, routes and migrations.

Don’t forget to run rake db:migrate and you are ready to go! But don’t stop reading here, we still have a lot to tell you.

Controller filters and helpers ↑

Devise will create some helpers to use inside your controllers and views. To set up a controller with user authentication, just add this before_filter:

before_filter :authenticate_user!

To verify if a user