README.rdoc

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.

Right now it's composed of 11 modules:

Database Authenticatable: encrypts and stores a password in the database to
validate the authenticity of an user while signing in. The authentication
can be done both through POST requests or HTTP Basic Authentication.

Token Authenticatable: signs in an 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.

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.

Installation

Devise 1.1 supports Rails 3 and is NOT backward compatible. You can use the
latest Rails 3 beta gem with Devise latest gem:

gem install devise --version=1.1.7

If you want to use Rails master (from git repository) you need to use
Devise from git repository and vice-versa.

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 you want to add devise, like User, Admin,
etc. This will create a model (if one does not exist) and configure it with
default Devise modules. The generator will also create a migration file (if
your ORM support them) and configure your routes. Continue reading this
file to understand exactly what the generator produces and how to use it.

Rails 2.3

If you want to use the Rails 2.3.x version, you should do:

gem install devise --version=1.0.10

And please check the README at the v1.0 branch since this one is based on
Rails 3:

http://github.com/plataformatec/devise/tree/v1.0

Ecosystem

Devise ecosystem is growing solid day after day. If you just need a
walkthrough about setting up Devise, this README will work great. But if
you need more documentation and resources, please check both the wiki and
rdoc:

Finally, Devise also has several extensions built by the community.
Don't forget to check them at the end of this README. If you want to
write an extension on your own, you should also check Warden (github.com/hassox/warden), a
Rack Authentication Framework which Devise depends on.

Basic Usage

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:

This will use your User model to create a set of needed routes (you can see
them by running `rake routes`).

Options for configuring your routes include :class_name (to set the class
for that route), :path_prefix, :path and :path_names, where the last two
have the same meaning as in common routes. The available :path_names are:

This exactly what the devise generator produces for you: 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 is signed in, use the following helper:

user_signed_in?

For the current signed-in user, this helper is available:

current_user

You can access the session for this scope:

user_session

After signing in a user, confirming the account or updating the password,
Devise will look for a scoped root path to redirect. Example: For a :user
resource, it will use user_root_path if it exists, otherwise default
root_path will be used. This means that you need to set the root inside
your routes:

root :to => "home"

You can also overwrite after_sign_in_path_for and after_sign_out_path_for
to customize your redirect hooks.

Finally, you need to set up default url options for the mailer in each
environment. Here is the configuration for
config/environments/development.rb:

Tidying up

Devise allows you to set up as many roles as you want. For example, you may
have a User model and also want an Admin model with just authentication,
trackable, lockable and timeoutable features and no confirmation or
password-recovery features. Just follow these steps:

Besides :encryptor, you can define :pepper, :stretches, :confirm_within,
:remember_for, :timeout_in, :unlock_in and other values. For details, see
the initializer file that was created when you invoked the “devise:install”
generator described above.

Configuring views

We built Devise to help you quickly develop an application that uses
authentication. However, we don't want to be in your way when you need
to customize it.

Since Devise is an engine, all its views are packaged inside the gem. These
views will help you get started, but after sometime you may want to change
them. If this is the case, you just need to invoke the following generator,
and it will copy all views to your application:

rails generate devise:views

However, if you have more than one role in your application (such as “User”
and “Admin”), you will notice that Devise uses the same views for all
roles. Fortunately, Devise offers an easy way to customize views. All you
need to do is set “config.scoped_views = true” inside
“config/initializers/devise.rb”.

After doing so, you will be able to have views based on the role like
“users/sessions/new” and “admins/sessions/new”. If no view is found within
the scope, Devise will use the default view at “devise/sessions/new”.

Configuring controllers

If the customization at the views level is not enough, you can customize
each controller by following these steps:

Test helpers

Devise includes some tests helpers for functional specs. To use them, you
just need to include Devise::TestHelpers in your test class and use the
sign_in and sign_out method. Such methods have the same signature as in
controllers:

You can include the Devise Test Helpers in all of your tests by adding the
following to the bottom of your test/test_helper.rb or spec/spec_helper.rb
file:

class ActionController::TestCase
include Devise::TestHelpers
end

Do not use such helpers for integration tests such as Cucumber or Webrat.
Instead, fill in the form or explicitly set the user in session. For more
tips, check the wiki (wiki.github.com/plataformatec/devise).

Migrating from other solutions

Devise implements encryption strategies for Clearance, Authlogic and
Restful-Authentication. To make use of these strategies, set the desired
encryptor in the encryptor initializer config option. You might also need
to rename your encrypted password and salt columns to match Devise's
fields (encrypted_password and password_salt).

Other ORMs

Devise supports ActiveRecord (by default) and Mongoid. We offer
experimental Datamapper support (with the limitation that the Devise test
suite does not run completely with Datamapper). To choose other ORM, you
just need to configure it in the initializer file.

Please consult their respective documentation for more information and
requirements.

TODO

Please refer to TODO file.

Security

Needless to say, security is extremely important to Devise. If you find
yourself in a possible security issue with Devise, please go through the
following steps, trying to reproduce the bug:

1) Look at the source code a bit to find out whether your assumptions are
correct; 2) If possible, provide a way to reproduce the bug: a small app on
Github or a step-by-step to reproduce; 3) E-mail us or send a Github
private message instead of using the normal issues;

Being able to reproduce the bug is the first step to fix it. Thanks for
your understanding.