Railsの第4世代認証エンジンDeviseのREADMEを翻訳してみた
Devise の README は懇切丁寧だが、その分クソ長いので、読むのに疲れる。後続のために訳してみることにした。無保証。OAuth2 の部分は飛ばした。長いし。差し迫ったら訳します。
Devise
Devise は Warden をベースにした Rails のためのフレキシブルな認証ソリューションです。
- Rackベース
- Rails エンジンに基づいた完全な MVC ソリューション
- 1回の認証で複数のロールを持たせることができます
- あなたが必要な部分だけ使えるモジュラー構造というコンセプトに基づいています
以下の11のモジュールで構成されています:
Database Authenticatable | ユーザーがサインインする時に認証するためにパスワードをデータベースに暗号化し保存します。この認証は POST リクエストまたはBasic認証を通して行われます。 |
Token Authenticatable | ("single access token"として知られる)認証トークンに基づいてサインインします。この認証トークンはクエリ文字列またはBasic認証を通して与えられます。 |
Oauthable | OAuth2 サポートを追加します。 |
Confirmable | 確認のためにEメールを送り、サインインの際に既に確認されたかどうか検査します。 |
Recorverble | パスワードをリセットし、リセットの指示を送ります。 |
Registerable | 登録プロセスを通してサインアップを処理します。また、アカウントを編集・削除できるようにします。 |
Rememberable | ユーザーを記憶するために、保存されたクッキーから、トークンを生成・消去を扱います。 |
Trackable | サインインのカウント・タイムスタンプ・IPアドレスを計測します。 |
Timeoutable | 特定の期間に活動がなかった場合、セッションを破棄します。 |
Validatable | Eメールとパスワードによる確認を提供します。これは、オプションでカスタマイズできるので、あなた専用の確認を定義できます。 |
Lockable | サインインの試みが特定の回数失敗したらアカウントをロックします。Eメール、または、特定の期間の後、アンロックできます。 |
インストール
Devise 1.1 は Rails 3 をサポートしており、後方互換性はありません。Devise の最新の Gem で、最新の Rails 3 で使うことができます。
gem install devise
Devise をインストールして、Gemfile に加えた後、ジェネレーターを起動できます。
rails generate devise:install
ジェネレーターは、Devise の全ての設定オプションをイニシャライザをインストールします。必ず確認してください。それが終わったら、ジェネレーターを使って Devise をモデルに追加する準備が出来ています。
rails generate devise MODEL
MODELの部分はあなたが Devise を加えたいクラス名、例えば User や Admin、に変更してください。これで(まだ存在してなければ)モデルを作成し、デフォルトの Devise モジュールが設定されます。このジェネレーターは(ORMがサポートしているならば)マイグレーションファイルも作成し、ルーティングも設定します。ジェネレーターが何を提供し、それをどうやって使うか、完全に理解するまで、この文書を読み続けてください。
Rails 2.3
If you want to use the Rails 2.3.x version, you should do:
もし、Rails 2.3.x バージョンで使いたいなら、
gem install devise --version=1.0.8
として下さい。
そして、v1.0 ブランチの README をチェックして下さい。
http://github.com/plataformatec/devise/tree/v1.0
エコシステム
Deviseのエコシステムは毎日成長しています。Devise の設定についてリハーサルが必要なら、この README は大いに役に立つでしょう。しかし、さらにドキュメントやリソースが必要ならば、Wiki と RDoc をチェックして下さい。
上記のリンクは Rails 3 用のものです、もし Rails 2.3 用のものが必要なら、gem をインストールした後で、コマンドラインで `gem server` を実行することで、古いドキュメントにアクセスすることができます。
Devise について学ぶもう1つのいい方法は、Ryan Bates のスクリーンキャストを見ることです:
- http://railscasts.com/episodes/209-introducing-devise
- http://railscasts.com/episodes/210-customizing-devise
そして、サンプルアプリケーションがいくつかあります:
- Rails 2.3 http://github.com/plataformatec/devise_example
- サブドメインを使った Rails 2.3 http://github.com/fortuity/subdomain-authentication
- Mongoid を使った Rails 3.0 http://github.com/fortuity/rails3-mongoid-devise
最後に、Devise はコミュニティによって作られたいくつかの拡張があります。この README の最後をチェックするのを忘れないで下さい。もし、あなた自身の拡張を書きたいならば、Devise が依存している、Rack の認証フレームワークである Warden (http://github.com/hassox/warden) を確認して下さい。
基本的な使い方
これは、モデル、マイグレーション、ルーティングとオプション設定を含んだ、あなたが必要とする全てのステップを含んだリハーサルです。
Devise はあなたが使用したいモデルの中で設定しなければなりません。
Devise のルーティングは、config/routes.rb ファイルの中で作成されなければなりません。
ここでは下記に書かれた Devise モジュールを User モデルに付け加えたいとします。
class User < ActiveRecord::Base devise :database_authenticatable, :confirmable, :recoverable, :rememberable, :trackable, :validatable end
使用するモジュールを選んだあと、マイグレーションを設定する必要があります。幸運にも、Devise は、この退屈な作業からあなたを救う、いくつかのヘルパーがあります。
create_table :users do |t| t.database_authenticatable t.confirmable t.recoverable t.rememberable t.trackable t.timestamps end
Devise はモジュールの中で attr_accessible や attr_protected を使用していません。なので、自分でモデルの中で定義するのを忘れないようにして下さい。
モデルの設定の後、ルーティングの設定をして下さい。config/routes.rb ファイルを開いて、以下を追加してください:
devise_for :users
これは必要なルーティングのセットです。`rake routes` で確認することができます。もし、Devise ジェネレーターを呼び出していれば、ジェネレーターがこれらのモデル、ルーティング、マイグレーションを生成してくれていることに気づくはずです。
rake db:migrate を実行するのを忘れないで下さい。これで準備が出来ました!しかし、これを読むのを止めないでください。まだ言うべきことが沢山あります。
コントローラー、フィルター、ヘルパー
Devise はいくつかのヘルパーをコントローラーとビューの中に生成します。ユーザー認証をコントローラーに組み込むために、次の before_filter を加えてください:
before_filter :authenticate_user!
ユーザーがサインインしているかどうか確認するには、次のヘルパーを使用してください:
user_signed_in?
現在サインインしてるユーザーのために、次のヘルパーがあります:
current_user
このスコープのセッションにアクセスできます:
user_session
サインインした後、アカウントの確認、パスワードを変更した後など、Devise はリダイレクトするためのスコープを探索します。例えば、:user リソースのスコープでは、user_root_path があればそこへリダイレクトします。なければ、デフォルトの root_path が使われます。つまり、ルーティングのの中に、root を設定する必要があります。
root :to => "home"
また、リダイレクトをカスタマイズするために、after_sign_in_path_for や after_sign_out_path_for といった命令で上書きできます。
最後に、メールのために、それぞれの環境で default url options を設定する必要があります。以下は、config/environments/development.rb の設定です:
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
おさらい
Devise はあなたが臨むだけのロールを設定できるようにします。例えば、既に User モデルがあって、さらにまた Admin モデルにも authentication, trackable, lockable and timeoutable といった機能を付け足したい、けど、onfirmation or password-recovery 機能はいらないといった場合、以下のようにすれば実現できます:
# 必要なフィールドでマイグレーションを作成する create_table :admins do |t| t.database_authenticatable t.lockable t.trackable t.timestamps end # Admin モデルの中で devise :database_authenticatable, :trackable, :timeoutable, :lockable # ルーティングの中で devise_for :admins # 保護したいコントローラーの中で before_filter :authenticate_admin! # コントローラーとビューの中で admin_signed_in? current_admin admin_session
(訳注:ここらへんで気力が尽きてきた。Twitterで元気玉を行使するも、@technohippyと@sota_kしか元気を分けてくれないのにふて腐れる。CERNのブラックホール実験が失敗してみんな吸い込まれればいい!)
モデルの設定
モデルの中の devise メソッドは、モジュールを設定するために、いくつかのオプションを受け付けます。例えば、database_authenticatable で使用する暗号化の方法を選択することができます。
devise :database_authenticatable, :confirmable, :recoverable, :encryptor => :bcrypt
:encryptor には、:pepper, :stretches, :confirm_within, :remember_for, :timeout_in, :unlock_in などが設定できます.詳細は "devise:install" ジェネレーターで生成されたイニシャライザファイルで確認してください。
ビューの設定
我々は、認証を用いるアプリケーションを素早く開発できるように Devise を作りました。しかしながら、あなたがカスタマイズしたい時には、邪魔をしたくありません。
Devise はエンジンですので、ビューが gem の中にパッケージされています。これらのビューは開始するのを助けますが、時には変更したい場合もあるかと思います。その時は、次のジェネレーターを実行して、アプリケーションにビューをコピーしてください。
rails generate devise:views
もし HAML を使っているなら、HAML に変換するために、hpricot が必要になります。
もし、アプリケーションの中で1つ以上のロールがある場合(例えば "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
コントローラーの設定
もし、ビューレベルでもカスタマイズでも充分でなかったら、次のステップでコントローラーもカスタマイズできます。
1) カスタムコントローラーを作成する。例えば Admins::SessionsController の場合:
class Admins::SessionsController < Devise::SessionsController end
2) ルーティングにこのコントローラーを使うように設定する:
devise_for :admins, :controllers => { :sessions => "admins/sessions" }
3) これでコントローラーを変更できました。"devise/sessions" ビューを使わないように、"devise/sessions" から "admin/sessions" へコピーするのを忘れないで下さい。
Devise は、サインインが成功または失敗した時に知らせるために flash メッセージを使用するのを覚えておいてください。Devise は、"flash[:notice]" と "flash[:alert]" が適切にアプリケーションから呼ばれることを期待します。
ルーティングの設定
Devise はデフォルトのルーティングもまた提供します。もしカスタマイズしたいなら、devise_for メソッドを使えば多分できます。devise_for メソッドは、国際化でパス名を変更することができるように、:class_name や :path_prefix といった、いくつかのオプションを受け入れます。
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/sign_in" の他に "/sign_in" も許したい場合など、ルーティングの中で devise_scope ブロックを使えばできます:
devise_scope :user do get "sign_in", :to => "devise/sessions#new" end
この方法は、"/sign_in" にアクセスされたとき :user スコープを使うことを意味しています。devise_scope はまた as というエイリアスがあります。好きな方を使ってください。
I18n
Devise は、:success や :failure といったキーの、国際化された flash メッセージを使います。カスタマイズするには、ロケールファイルを設定して下さい:
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'
何のメッセージが変更できるかはロケールファイルを見てください。
テストヘルパー
Devise は機能テストのためにいくつかのテストヘルパーを含んでいます。それを使用するには、テストクラスで Devise::TestHelpers をインクルードして、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)
test/test_helper.rb ファイルの末尾に以下の記述を追加することで、全てのテストで Devise のテストヘルパーを使うことができます:
class ActionController::TestCase include Devise::TestHelpers end
もし、RSpec を使っていて、全ての describe ブロックで自動的にヘルパーを使いたいなら、以下の内容の spec/support/devise.rb というファイルを作成して下さい:
RSpec.configure do |config| config.include Devise::TestHelpers, :type => :controller end
これらのヘルパーは、Cucumber や Webrat のようなインテグレーションテストでは使わないでください。その代わりに、フォームを埋めるか、セッションにユーザーをセットして下さい。更なる Tips は Wiki (http://wiki.github.com/plataformatec/devise) をチェックして下さい。
OAuth2
(今回は略)
他のソリューションからの移行
Devise は Clearance、Authlogic、Restful-Authentication らの暗号化方法を組み込んであります。これらの方法を使うために、イニシャライザの設定オプションで求める暗号化方法をセットして下さい。また、Deviseのフィールド(encrypted_password と password_salt)に合わせるために、暗号化パスワードとソルトのカラム名を変更する必要があります。
その他のORM
Devise は ActiveRecord (default) と Mongoid をサポートしています。その他の ORM を選択するには、イニシャライザファイルで require する必要があります。
拡張
Devise にはまた、コミュニティによって作られた拡張があります。
Devise also has extensions created by the community:
- http://github.com/scambra/devise_invitable は招待メール機能を付け加えます
- http://github.com/joshk/devise_imapable は、LDAPサーバがない時の社内アプリなどのために、IMAP ベースの認証を付け加えます
- http://github.com/cschiewek/devise_ldap_authenticatable は LDAP 認証を付け加えます
更なる情報と必要事項は、それぞれのドキュメントを調べてください。
バグとフィードバック
もし、バグを見つけたときは、ぜひ知らせてください。その際は、必ず Devise と Rails のバージョンと、できるなら関連した情報を含めてください。できれば、以下のステップを通してください。
1) あなたの仮定が正しいことを見つけるために、ソースコードをちょっとみてください。我々は、できるだけクリーンにそしてドキュメントを書くようにしています。
2) バグを再現する簡単な方法を提供してください。Githubで、Devise のテストスイートに小さなテストを追加するか、小さなアプリケーションで。
私達の Issues Tracker はここにあります:
もし、セキュリティバグを見つけた場合は、Issues Tracker を使わないで、Githubのプライベートメッセージか、開発者へのEメールで知らせて下さい。
最後に、質問があったり、なにかフィードバックが欲しい時は、Issues Tracker の代わりにメーリングリストを使ってください。
貢献者
価値ある貢献をしてくれた人々の長いリストがあります。ここでチェックして下さい:
もし、新しい機能を追加したい場合、Issues Tracker で教えてください!もし、かゆいところがあったら、リポジトリの TODO ファイルをチェックしてみてください :)
メンテナ
- José Valim (http://github.com/josevalim)
- Carlos Antônio da Silva (http://github.com/carlosantoniodasilva)
ライセンス
MIT License. Copyright 2010 Plataforma Tecnologia. http://blog.plataformatec.com.br
(訳注:疲れた〜。下のアフィリをクリックして MacBook でも買うといいよ!もしくは、babie.tanaka@gmail.com 宛に Amazonギフト券500円分送るといいよ!ニューアサマシ!!)