README.md in loyal_devise-2.1.2 vs README.md in loyal_devise-2.1.3
- old
+ new
@@ -1,19 +1,23 @@
-## Devise
+
-[](http://travis-ci.org/plataformatec/devise) [](https://codeclimate.com/github/plataformatec/devise)
+By [Plataformatec](http://plataformatec.com.br/).
+[](http://badge.fury.io/rb/devise)
+[](http://travis-ci.org/plataformatec/devise)
+[](https://codeclimate.com/github/plataformatec/devise)
+
This README is [also available in a friendly navigable format](http://devise.plataformatec.com.br/).
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:
+It's composed of 11 modules:
* [Database Authenticatable](http://rubydoc.info/github/plataformatec/devise/master/Devise/Models/DatabaseAuthenticatable): 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](http://rubydoc.info/github/plataformatec/devise/master/Devise/Models/TokenAuthenticatable): 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](http://rubydoc.info/github/plataformatec/devise/master/Devise/Models/Omniauthable): adds Omniauth (https://github.com/intridea/omniauth) support;
* [Confirmable](http://rubydoc.info/github/plataformatec/devise/master/Devise/Models/Confirmable): sends emails with confirmation instructions and verifies whether an account is already confirmed during sign in.
@@ -51,11 +55,11 @@
You can view the Devise documentation in RDoc format here:
http://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.
+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:
@@ -84,11 +88,11 @@
Once you have solidified your understanding of Rails and authentication mechanisms, we assure you Devise will be very pleasant to work with. :)
## Getting started
-Devise 2.0 works with Rails 3.1 onwards. You can add it to your Gemfile with:
+Devise 3.0 works with Rails 3.2 onwards. You can add it to your Gemfile with:
```ruby
gem 'devise'
```
@@ -104,11 +108,11 @@
```console
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 "rake 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 to point to the Devise controller.
+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 `rake 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 to point to the Devise controller.
Note that you should re-start your app here if you've already started it. Otherwise you'll run into strange errors like users being unable to login and the route helpers being undefined.
### Controller filters and helpers
@@ -137,11 +141,11 @@
```
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:
```ruby
-root :to => "home#index"
+root to: "home#index"
```
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":
@@ -170,38 +174,61 @@
devise :database_authenticatable, :registerable, :confirmable, :recoverable, :stretches => 20
```
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
+### Strong Parameters
-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 and timeoutable features. If so, just follow these steps:
+When you customize your own views, you may end up adding new attributes to forms. Rails 4 moved the parameter sanitization from the model to the controller, causing Devise to handle this concern at the controller as well.
+There are just three actions in Devise that allows any set of parameters to be passed down to the model, therefore requiring sanitization. Their names and the permited parameters by default are:
+
+* `sign_in` (`Devise::SessionsController#new`) - Permits only the authentication keys (like `email`)
+* `sign_up` (`Devise::RegistrationsController#create`) - Permits authentication keys plus `password` and `password_confirmation`
+* `account_update` (`Devise::RegistrationsController#update`) - Permits authentication keys plus `password`, `password_confirmation` and `current_password`
+
+In case you want to customize the permitted parameters (the lazy way™) you can do with a simple before filter in your `ApplicationController`:
+
```ruby
-# Create a migration with the required fields
-create_table :admins do |t|
- t.string :email
- t.string :encrypted_password
- t.timestamps
+class ApplicationController < ActionController::Base
+ before_filter :configure_permitted_parameters, if: :devise_controller?
+
+ protected
+
+ def configure_permitted_parameters
+ devise_parameter_sanitizer.for(:sign_in) { |u| u.permit(:username, :email) }
+ end
end
+```
-# Inside your Admin model
-devise :database_authenticatable, :timeoutable
+If you have multiple roles, you may want to set up different parameter sanitizer per role. In this case, we recommend inheriting from `Devise::ParameterSanitizer` and add your own logic:
-# Inside your routes
-devise_for :admins
+```ruby
+class User::ParameterSanitizer < Devise::ParameterSanitizer
+ def sign_in
+ default_params.permit(:username, :email)
+ end
+end
+```
-# Inside your protected controller
-before_filter :authenticate_admin!
+And then configure your controllers to use it:
-# Inside your controllers and views
-admin_signed_in?
-current_admin
-admin_session
+```ruby
+class ApplicationController < ActionController::Base
+ protected
+
+ def devise_parameter_sanitizer
+ if resource_class.is_a?(User)
+ User::ParameterSanitizer.new(User, :user, params)
+ else
+ super # Use the default one
+ end
+ end
+end
```
-On the other hand, you can simply run the generator!
+The example above overrides the permitted parameters for the user to be both `:username` and `:email`. The non-lazy way to configure parameters would be by defining the before filter above in a custom controller. We detail how to configure and customize controllers in some sections below.
### 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.
@@ -221,33 +248,35 @@
### Configuring controllers
If the customization at the views level is not enough, you can customize each controller by following these steps:
-1) Create your custom controller, for example a Admins::SessionsController:
+1. Create your custom controller, for example a `Admins::SessionsController`:
-```ruby
-class Admins::SessionsController < Devise::SessionsController
-end
-```
+ ```ruby
+ class Admins::SessionsController < Devise::SessionsController
+ end
+ ```
-2) Tell the router to use this controller:
+ Note that in the above example, the controller needs to be created in the `app/controller/admins/` directory.
-```ruby
-devise_for :admins, :controllers => { :sessions => "admins/sessions" }
-```
+2. Tell the router to use this controller:
-3) And since we changed the controller, it won't use the "devise/sessions" views, so remember to copy "devise/sessions" to "admin/sessions".
+ ```ruby
+ devise_for :admins, :controllers => { :sessions => "admins/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[:notice]" and "flash[:alert]" as appropriate. Do not print the entire flash hash, print specific keys or at least remove the `:timedout` key from the hash as Devise adds this key in some circumstances, this key is not meant for display.
+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[:notice]"` and `"flash[:alert]"` as appropriate. Do not print the entire flash hash, print specific keys or at least remove the `:timedout` key from the hash as Devise adds this key in some circumstances, this key is not meant for display.
+
### 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:
```ruby
-devise_for :users, :path => "usuarios", :path_names => { :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification', :unlock => 'unblock', :registration => 'register', :sign_up => 'cmon_let_me_in' }
+devise_for :users, :path => "auth", :path_names => { :sign_in => 'login', :sign_out => 'logout', :password => 'secret', :confirmation => 'verification', :unlock => 'unblock', :registration => 'register', :sign_up => 'cmon_let_me_in' }
```
Be sure to check `devise_for` documentation for details.
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:
@@ -328,45 +357,76 @@
sign_out @user # sign_out(resource)
```
There are two things that is important to keep in mind:
-1) These helpers are not going to work for integration tests driven by Capybara or Webrat. They are meant to be used with functional tests only. Instead, fill in the form or explicitly set the user in session;
+1. These helpers are not going to work for integration tests driven by Capybara or Webrat. They are meant to be used with functional tests only. Instead, fill in the form or explicitly set the user in session;
-2) If you are testing Devise internal controllers or a controller that inherits from Devise's, you need to tell Devise which mapping should be used before a request. This is necessary because Devise gets this information from router, but since functional tests do not pass through the router, it needs to be told explicitly. For example, if you are testing the user scope, simply do:
+2. If you are testing Devise internal controllers or a controller that inherits from Devise's, you need to tell Devise which mapping should be used before a request. This is necessary because Devise gets this information from router, but since functional tests do not pass through the router, it needs to be told explicitly. For example, if you are testing the user scope, simply do:
+ ```ruby
@request.env["devise.mapping"] = Devise.mappings[:user]
get :new
+ ```
### Omniauth
-Devise comes with Omniauth support out of the box to authenticate from other providers. You can read more about Omniauth support in the wiki:
+Devise comes with Omniauth support out of the box to authenticate with other providers. To use it, just specify your omniauth configuration in `config/initializers/devise.rb`:
+```ruby
+config.omniauth :github, 'APP_ID', 'APP_SECRET', :scope => 'user,public_repo'
+```
+
+You can read more about Omniauth support in the wiki:
+
* https://github.com/plataformatec/devise/wiki/OmniAuth:-Overview
-### Other ORMs
+### Configuring multiple models
-Devise supports ActiveRecord (default) and Mongoid. To choose other ORM, you just need to require it in the initializer file.
+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 and timeoutable features. If so, just follow these steps:
-### Migrating from other solutions
+```ruby
+# Create a migration with the required fields
+create_table :admins do |t|
+ t.string :email
+ t.string :encrypted_password
+ t.timestamps
+end
-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).
+# Inside your Admin model
+devise :database_authenticatable, :timeoutable
-## Troubleshooting
+# Inside your routes
+devise_for :admins
+# Inside your protected controller
+before_filter :authenticate_admin!
+
+# Inside your controllers and views
+admin_signed_in?
+current_admin
+admin_session
+```
+
+On the other hand, you can simply run the generator!
+
+### Other ORMs
+
+Devise supports ActiveRecord (default) and Mongoid. To choose other ORM, you just need to require it in the initializer file.
+
+## Additional information
+
### Heroku
Using devise on Heroku with Ruby on Rails 3.1 requires setting:
```ruby
config.assets.initialize_on_precompile = false
```
Read more about the potential issues at http://guides.rubyonrails.org/asset_pipeline.html
-## 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:
https://github.com/hassox/warden
@@ -383,6 +443,8 @@
* Carlos Antônio da Silva (https://github.com/carlosantoniodasilva)
* Rodrigo Flores (https://github.com/rodrigoflores)
## License
-MIT License. Copyright 2012 Plataformatec. http://plataformatec.com.br
+MIT License. Copyright 2009-2013 Plataformatec. http://plataformatec.com.br
+
+You are not granted rights or licenses to the trademarks of the Plataformatec, including without limitation the Devise name or logo.