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.

It's composed of 12 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 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.

Contributing

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 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.

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

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:

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 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:

Besides :stretches, you can define :pepper, :encryptor, :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 multiple models

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:

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

If you are using HAML, you will need hpricot installed to convert Devise
views to HAML.

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”. You
can also use the generator to generate scoped views:

rails generate devise:views users

Configuring controllers

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

3) And since we changed the controller, it won't use the
“devise/sessions” views, so remember to copy “devise/sessions” to
“admin/sessions”.

Remember that Devise uses flash messages to let users know if sign in was
successful or failed. Devise expects your application to call “flash” and “flash” as
appropriate.

Configuring routes

Devise also ships with default routes. If you need to customize them, you
should probably be able to do it through the devise_for method. It accepts
several options like :class_name, :path_prefix and so on, including the
possibility to change path names for I18n:

If you have the need for more deep customization, for instance to also
allow “/sign_in” besides “/users/sign_in”, all you need to do is to create
your routes normally and wrap them in a devise_scope block in the
router:

devise_scope :user do
get "sign_in", :to => "devise/sessions#new"
end

This way you tell devise to use the scope :user when “/sign_in” is
accessed. Notice devise_scope is also aliased as as and
you can also give a block to devise_for, resulting in the same
behavior:

devise_for :users do
get "sign_in", :to => "devise/sessions#new"
end

Feel free to choose the one you prefer!

I18n

Devise uses flash messages with I18n with the flash keys :success and
:failure. To customize your app, you can set up your locale file:

en:
devise:
sessions:
signed_in: 'Signed in successfully.'

You can also create distinct messages based on the resource you've
configured using the singular name given in routes:

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:

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).

OAuth2

Devise comes with OAuth support out of the box if you're using Devise
from the git repository (for now). You can read more about OAuth2 support
in the wiki:

Other ORMs

Devise supports ActiveRecord (default) and Mongoid. To choose other ORM,
you just need to require it in the initializer file.

Migrating from other solutions

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

Additional information

Warden

Devise is based on Warden, which is a general Rack authentication framework
created by Daniel Neighman. We encourage you to read more about Warden
here: