この記事は、2015年6月8日現在の翻訳です。
これ以降の変更は対応していません。

Devise

DeviseはWardenベースのRails用認証ソリューションです。
Deviseは以下の特徴があります。

Rackベース
Railsエンジンで動作する完全なMVCソリューション
同時に複数のモデルでサインイン可能
本当に必要なモノだけを使えるようなモジュール方式のコンセプト

次の10のモジュールから構成されています。

Database Authenticable: ユーザがサインインするための認証パスワードを暗号化しDBに保存します
Omniauthable: OmniAuthをサポートします
Confirmable: 確認フロー中にメールを送付し、サインインの際にアカウントが確認済みか否かをチェックします
Recoverable: パスワードのリセットをし、リセット方法をメールで送付します
Registerable: 登録プロセスを通してユーザのサインアップを行い、ユーザ情報の編集や削除機能を有します
Rememberable: ユーザ情報をクッキーに保存するため、トークンを生成・削除します
Trackable: サインイン回数、サインイン時間、IPアドレスを保存します
Timeoutable: 特定の時間でセッションの有効期限を切ることができます
Validatable: emailとパスワードのバリデーションが可能です。これはオプションであり、カスタマイズ可能であるため、独自バリデーション機能を定義できます
Lockable: サインインに特定の回数失敗したのち、アカウントをロックします。メールもしくは特定の時間ののちアンロック可能です

Information

The Device Wiki

The Devise Wikiには、たくさんの"how to"記事やFAQを含む情報があります。READMEを読んだ後、見に行ってください。

Bug reports

Deviseに問題を発見したら、教えてほしいです。以下のガイドラインを読んだ後、バグレポートをあげてください。

万が一セキュリティ関連のバグを発見した場合は、GitHubのイシュートラッカーを利用しないでください。以下のメールアドレスへ連絡ください。
opensource@plataformatec.com.br

Mailing list

質問、コメントなどは、GitHubイシュートラッカーではなく、Google Groupsを利用してください。

RDocs

DeviseのドキュメントはRDocフォーマットでも利用可能です。

以前のバージョンのRailsでDeviseを利用する必要がある場合は、過去のドキュメントを確認するため、gemをインストールしたのち、"gem server"をコマンドラインで走らせてください。

Example applications

複数のバージョンのRails上でDeviseの各種機能を動作させるデモアプリケーションサンプルをGitHubで入手可能です。

Extensions

コミュティでは、Deviseを高機能にするたくさんのextensionを作成しています。以下のページで入手可能なextensionのリストを閲覧・入手できます。

Contributing

Deviseへの貢献をお待ちしております。以下の概要を確認してください。

変更に対してはテストを書くと思います。テストスイートを走らせる場合は、Deviseのトップディレクトリを行き、"bundle install"および"rake"を実行してください。テストをパスさせるため、システムにはMongoDBサーバ(2.0以上)が必要になります。

Starting with Rails?

もし、Railsアプリケーションの構築が初めての場合は、Deviseはおすすめしません。DeviseはRailsフレームワークを熟知する必要があります。スクラッチで一度シンプルな認証システムを構築することをおすすめします。次の2つのリソースが参考になるでしょう。

Railsと認証の仕組みを理解したのち、Deviseは非常に有用だとわかります

Getting started

Devise 3.0は、Rails 3.2以上で動作します。Gemfileに追加します。

gem 'devise'

bundleコマンドを実行してください。
Deviseをインストールした後、generatorを実行してください。

rails generate devise:install

generatorは、全てのDevise設定オプションのinitializerをインストールします。一度、必ず確認してください。終わったら、generatorを利用してDeviseを好きなモデルに追加してください。

rails generate devise MODEL

MODELはアプリケーションのユーザを表す名前のクラスに書き換えてください(Userであることが多いですが、Adminかもしれません)。これにより、(もし存在しなければ)モデルが生成され、Deviseモジュールとして設定されます。generatorは、config/routes.rbファイルもDeviseコントローラを指すように修正します。

次に、メール確認やアカウントロックなどのモデルに追加したいオプション設定をチェックしてください。オプションを追加した場合は、(ORMがサポートしていればgeneratorによって作成される)migrationファイルも確認し、適切なセクションのコメントを外してください。例えば、メール確認のオプションを追加した場合、Confirmableセクションのコメントを外す必要があります。そのあとrake db:migrateを実行してください。

次は、各環境のDevise用メールサーバの設定をします。以下は、config/environments/development.rb用の設定例です。

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

Deviseの設定を変更したら、アプリケーションを再起動してください。再起動しないと、ログインできなかったりルーティング設定が壊れているというエラーが発生する可能性があります。

Controller filters and helpers

Deviseは、controllerやviewで利用可能なhelperを生成します。ユーザ認証をcontrollerに設定するには、before_actionを追加するだけです(以下は、Deviseのmodelが'User'の例です)。

before_action :authenticate_user!

DeviseのmodelがUserではない場合、"_user"の部分を"_yourmodel"に変更してください。これから紹介する内容が利用できるようになります。

ユーザがサインイン済みかをチェックするには、次のhelperを利用します。

user_signed_in?

現在サインイン中のユーザについては、このhelperが利用可能です。

current_user

セッションにもアクセスできます。

user_session

サインイン、アカウントの確認、パスワードの変更などを行った後、Deviceは画面をリダイレクトするためrootパスを探します。例えば、:userリソースを利用しているのであれば、user_root_pathが存在しているなら、それが使われます。そうでなければ、デフォルトのroot_pathが使われます。つまり、ルーティングにrootを設定する必要があるということです。

root to: "home#index"

さらに、after_sign_in_path_forやafter_sign_out_path_forをオーバーライドしてリダイレクトフックをカスタマイズできます。
DeviseのmodelがUserではなくMemberの場合、以下のようなhelperが利用可能です。

before_action :authenticate_member!

member_signed_in?

current_member

member_session

Configuring Models

model内のDeviseメソッドで、該当のモジュールの設定を行うことが可能です。例えば、以下のように暗号化アルゴリズムの選択が可能です。

devise :database_authenticatable, :registerable, :confirmable, :recoverable, :stretches: 20

:stretchesでは、 :pepper、 :encryptor、 :confirm_within、 :remember_for、 :timeout_in、 :unlock_in のオプションを定義できます。さらに詳しい情報は、上で説明した"devise:install"のgeneratorが呼び出されたときに生成されたinitializerファイルを確認してください。このファイルは通常、/config/initializers/devise.rbにあります。

Strong Parameters

独自ビューをカスタマイズする際に、フォームに新しい属性を追加する必要があります。Rails 4では、パラメータのサニタイズをmodelからcontrollerへ移しました。これにより、Deviseはcontrollerでもこの問題を扱えるようになりました。

サニタイズが必要な場合、Deviseでは3つのアクションによりmodelへ各パラメータを渡すことができます。デフォルトでは以下の名前とパラメータになります。

sign_in(Devise::SessionsController#create) - 認証キー(例えばemail)のみを許可します
sign_up(Devise::RegistrationsController#create) - 認証キーに加え、passwordとpassword_confirmationを許可します
account_update(Devise::RegistrationsController#update) - 認証キーに加え、passwordとpassword_confirmation、current_passwordを許可します

もしその他のパラメータを追加した場合は(the lazy way)、ただbeforeフィルタをApplicationControllerを追加します。

class ApplicationController < ActionController::Base
  before_action :configure_permitted_parameters, if: :devise_controller?

  protected

  def configure_permitted_parameters
    devise_parameter_sanitizer.for(:sign_up) << :username
  end
end

上記のコードは、パラメータが単純なスカラータイプである場合どんな追加パラメータでも動作します。ネストされた属性の場合(accepts_nested_attributes_forを利用している場合)、ネストされていることとそのタイプをDeviseに伝える必要があります。デフォルト設定を全部変更したり、カスタマイズした振る舞いをさせることもできます。

ユーザ名とemailを許可する場合は以下のようにします。

def configure_permitted_parameters
  devise_parameter_sanitizer.for(:sign_in) { |u| u.permit(:username, :email) }p
end

もし、登録の際にユーザにロールを割り当てるためのチェックボックスがある場合は、ブラウザはチェックボックスを配列で渡します。配列は、Strong Parameterで許可されていないため、以下のようにDeviseを設定する必要があります。

def configure_permitted_parameters
  devise_parameter_sanitizer.for(:sign_up) { |u| u.permit({ roles: [] }, :email, :password, :password_confirmation) }
end

許可値リストや、ネストしたハッシュや配列からキーをどのように宣言するかについては以下を確認してください。

Deviseのモデルが複数ある場合は、モデルごとに異なるパラメタに対するサニタイザを設定したくなると思います。この場合は、Devise::ParameterSanitizerを継承した上で、ロジックを追加することを進めます。

class User::ParameterSanitizer < Devise::ParameterSanitizer
  def sign_in
    default_params.permit(:username, :email)
  end
end

その上で、コントローラの中で利用してください。

class ApplicationController < ActionController::Base
  protected

  def devise_parameter_sanitizer
    if resource_class == User
      User::ParameterSanitizer.new(User, :user, params)
    else
      super # Use the default one
    end
  end
end

上記の例では、userの:usernameと:emailの両方に適用されるようpermitted parametersをオーバライドしています。まじめにやろうとすると、カスタムコントローラで、beforeフィルタを定義することによりパラメータを設定することになります。以降のセクションで、コントローラを設定し、カスタマイズする方法の詳細を説明します。

Configuring views

ここまでは、認証を利用するアプリケーションを簡単に開発するためDeviseを利用しました。しかし、カスタマイズする必要がある場合もある。
Deviseはエンジンであるため、gemの中にビューが全てパッケージされている。これらのビューは始めたばかりの時には役立ちますが、作業をしているうちに変更したくなります。こうした場合は、次のようにgeneratorを呼び出して、アプリケーションにすべてのビューをコピーしてください。

rails genrate devise:views

アプリケーション内に複数のモデル(UserとAdminなど)がある場合は、Deviseがすべてのモデルで同じビューを利用することを念頭においてください。幸運なことに、Deviseではビューを簡単にカスタマイズすることができます。config/initializers/devise.rbファイルにconfig.scoped_views = trueをセットするだけです。

そうしたら、users/sessions/newやadmins/sessions/newのようにロールごとにビューを持つことができます。ビューが適切な場所に存在しない場合は、Deviseは、devise/sessions/newというデフォルトビューを利用します。モデルごとのビューを作りたい場合は、以下のようにします。

rails generate devise:views users

「registerableとconfrimableモジュールだけ」というような、ビューのうちいくつかだけを生成したい場合は、-vフラグでモジュールのリストをgeneratorに渡します。

rails generate devise:views -v registrations confirmations

Configuring controllers

ビューのカスタマイズだけでは足りない場合、以下のステップで、ビューをカスタマイズすることができます。

スコープをgeneratorに渡して、コントローラを作成します

   rails generate devise:controllers [scope]

スコープとしてusersを使いたい場合、コントローラはapp/controllers/user/に作成されます。セッションコントローラは以下のような感じです。

   class Users::SessionsController < Devise::SessionsController
      # GET /resource/sign_in
      # def new
      #   super
      # end
      ...
   end

コントローラを利用するためのルーティング設定をします

   devise_for :users, controllers: { sessions: "users/sessions" }

devise/sessions/からusers/sessionsにビューをコピーします。コントローラがへ高されたので、devise/sessionsにあるデフォルトビューは使われません。
最後に、コントローラ上でアクションを変更もしくは拡張します。
コントローラのアクションを完全にオーバライドすることもできます。
```
 class Users::SessionsController < Devise::SessionsController
   def create
     # custom sign-in code
   end
 end
```
もしくは単に新しい振る舞いを追加することもできます。
```
 class Users::SessionsController < Devise::SessionsController
   def create
     super do |resource|
     BackgroundWorker.trigger(resource)
     end
   end
 end
```
上記のコードはバックグラウンドジョブのトリガーや、特定のアクション中のロギングイベントに有効です。

Deviseは、サインインの成功や失敗を伝えるのにflashメッセージを利用します。Deviseでは、アプリケーション内でflash[:notice]やflash[:alert]を適切に利用してください。flashハッシュのすべてを表示するのではなく、特定のキーを表示してください。特定の環境においては、Deviseは:timeoutキーをflashハッシュとして追加しますが、表示にはテキしていません。もしハッシュをそのまま表示するつもりなら、このキーは削除してください。

Configuring routes

Deviseは、デフォルトでルーティングを設定します。カスタマイズする必要があれば、devise_forメソッドを使ってカスタマイズしてもよいでしょう。以下のようにi18n対応のパスを許可するものを含め、:class_nameや:path_prefixなどのオプションがあります。

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' }

詳細はdevise_forのデモを確認してください。

例えば"/users/sign_in"に加え"/sign_in"を許可したいなど、さらなるカスタマイズが必要な場合は、通常通りルーティングの設定を行い、devise_scopeブロックで囲うだけでOKです。

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

このように設定すると、"/sign_in"にアクセスがあると、Deviseは:userスコープを利用します。devise_scopeはルーティング設定内ではasとしてもエイリアスされています。

I18n

Deviseは、:noticeや:alertというフラッシュキーで接続された、I18nのflashメッセージを利用します。アプリケーションをカスタマイズするためには、localeファイルを設定してください。

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

ルーティング設定内で特定可能な名前を利用することで、リソースごとに異なるメッセージを作成することもできます。

en:
  devise:
    sessions:
      user:
        signed_in: 'Welcome user, you are signed in.'
      admin:
        signed_in: 'Hello admin!'

Deviseのメーラは、件名を同様にして独立して定義されたものを利用します。

en:
  devise:
    mailer:
      confirmation_instructions:
        subject: 'Hello everybody!'
        user_subject: 'Hello User! Please confirm your email'
      reset_password_instructions:
        subject: 'Reset instructions'

利用可能なメッセージについては、以下のlocaleファイルをご覧ください。wikiにある翻訳も利用可能です。

注意: Devise Controllersは、ApplicationControllerを継承しています。アプリ内で複数のlocaleを利用する場合は、ApplicationControllerでI18n.localeを設定しなくてはなりません。

Test helpers

Deviseはspec用にtest helperを含んでいます。利用するには、test/test_helper.rbファイルの最後に以下のコードを追加します。

class ActionController::TestCase
  include Devise::TestHelpers
end

RSpecを利用しているのであれば、spec/support/devise.rbかspec/spec_helper.rb(もしくは、rspec-railsを利用しているのであればspec/rails_helper.rb)というファイルに以下のコードを埋めてください。

RSpec.configure do |config|
  config.include Devise::TestHelpers, type: :controller
end

require 'rspec/rails'ディレクティブの後で有効であることに気をつけてください。

これで、sign_inやsign_outメソッドが利用できる準備が整いました。これらのメソッドはコントローラ内で利用可能です。

sign_in :user, @user   # sign_in(scope, resource)
sign_in @user          # sign_in(resource)

sign_out :user         # sign_out(scope)
sign_out @user         # sign_out(resource)

覚えておくべきことがふたつあります。

これらのhelperは、CapybaraやWebratによる結合試験では利用できません。機能試験のみで利用できます。フォームへ入力するかセッションにユーザをセットしてください。
Deviseの内部コントローラやDevise自体を継承したコントローラを試験する場合は、リクエストの前にどのマッピングが使われるかをDeviseに知らせる必要があります。これはDeviseがルータからこの情報を得るためですが、機能テストはルータを通さないので明確にする必要があります。例えば、userスコープをテストする場合は、シンプルに以下のように記載します。

@request.env["devise.mapping"] = Devise.mappings[:user]
get :new

RSpecでのRails3、Rails4のコントローラの試験については、以下のwikiで詳細を確認してください。

https://github.com/plataformatec/devise/wiki/How-To:-Test-controllers-with-Rails-3-and-4-%28and-RSpec%29

OmniAuth

Deviseは、すぐに様々な認証を利用できるOmniAuthをサポートしています。利用するには、OmniAuthの設定をconfig/initializers/devise.rbに記載します。

config.omniauth :github, 'APP_ID', 'APP_SECRET', scope: 'user,public_repo'

wikiにさらに詳細な情報があります。

https://github.com/plataformatec/devise/wiki/OmniAuth:-Overview

Configuring multiple models

Deviseは好きなだけモデルをセットアップできます。上記のUserモデルに加え、認証にタイムアウト機能を備えただけのAdminモデルを作りたい場合は、以下のようにします。

# Create a migration with the required fields
create_table :admins do |t|
  t.string :email
  t.string :encrypted_password
  t.timestamps null: false
end

# Inside your Admin model
devise :database_authenticatable, :timeoutable

# 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

あるいは、Devise generatorを呼ぶ出すだけでも可能です。

これらのモデルは完全に異なるルーティングになることを注意してください。サインイン、サインアウトなどについて、コントローラを共有することは ありませんし 、 できません 。同じアクションを異なるロールで共有したい場合は、ロールのカラムを使うか、それに特化したgemを利用するというようなロールベースのアプローチをお勧めします。

ActiveJob Integration

バックエンドでのキューイング用にActionMailerのメッセージ配信をするために、Rail4.2とActiveJobを利用している場合は、モデル内でsend_devise_notificationメソッドをオーバーライドすることにより既存のキューを通してDeviseのメールを送信することができます。

def send_devise_notification(notification, *args)
  devise_mailer.send(notification, self, *args).deliver_later
end

Password reset tokens and Rails logs

Recoverableモジュールを有効にする場合は、パスワードリセットのトークンが盗まれると、攻撃者がアプリケーションにアクセスできてしまうことに注意してください。Deviseは、ランダムでセキュアなトークンを生成し、データベースにトークンのdigestのみを保存します。これは平文ではありません。しかしながら、Railsにおけるデフォルトのロギングでは、ログファイルに平文のtokenを漏らしてしまいます。

Action MailerはDEBUGレベルにて、送付メールのすべてのコンテンツをログに出力します。ユーザに送付されたパスワードリセットのトークンが漏れることになります。
Active JobはINFOレベルにて、各キューに対する全ての引数をログに出力します。パスワードリセットのメールを送付するためにdeliver_laterをDeviseで設定した場合、パスワードリセットのトークンが漏れることになります。

RailsはデフォルトでproductionのログレベルをDEBUGに設定します。ログにトークンが出力されないようにしたいのであれば、productionのログレベルをWARNに変更してください。config/environments/production.rb内で以下のように設定します。

config.log_level = :warn

Other ORMs

Deviseは、ActiveRecord（デフォルト）とMongoidをサポートしています。他のORMを利用するためには、initializerファイルでrequireしてください。

Additional information

Heroku

Ruby on Rails 3.2のHeroku上でDeviseを使うには、以下のように設定します。

config.assets.initialize_on_precompile = false

その他の潜在的な問題については、http://guides.rubyonrails.org/asset_pipeline.html で紹介されています。

Warden

DeviseはWardenをベースにしています。Wardenは、Daniel Neighmanによって構築されたRackベースの認証フレームワークです。Wardenについては以下が参考になります。

Contributors

DeviseにはたくさんのContributorがいます。以下に全員記載してます。

Lisence

You are not granted rights or licenses to the trademarks of Plataformatec, including without limitation the Devise name or logo.

DeviseのREADMEを翻訳してみた