Rails用認証ライブラリ Monban(門番) READMEの和訳

本記事は、[Rails用認証ライブラリMonban](https://github.com/halogenandtoast/monban)の[英文README](https://github.com/halogenandtoast/monban/blob/master/README.md)の和訳です。まだ完全ではないですが、凡そ出来たので公開します。もし誤りがあれば編集リクエストかコメントをください。

---

# Monban 門番

Monban は、Rails用のとてもシンプルで、拡張可能なユーザー認証ライブラリとして設計されています。Its goal is to give all the power to the developer instead of forcing them to make Monban work with their system.(分かりやすく翻訳できない)

## なぜMonbanを使うのか？

Monbanはユーザー認証をシンプルにします:

- 依存性の注入を利用してテストが簡単に書ける
- 便利なコントローラーヘルパーを提供する
- 拡張性が高い

Monbanは以下のことをしません:

- あなたのアプリケーションに 勝手にルーティングを追加しない
- Railsエンジンベースのコントローラーやビューの使用を強制しない
- あなたのモデルの変更をする必要がない

## ドキュメント

全てのドキュメントは[rubydoc](http://rubydoc.info/github/halogenandtoast/monban)で読めます。

## インストール

MonbanはRails4.0以上で動作するように設計されています。あなたのGemfileに以下を追加してください:

    gem 'monban'

次にあなたのApplicationController内に以下を追加してください:

    include Monban::ControllerHelpers

これで認証システムを開始する準備が出来ました。

## ジェネレーター

もしあなたがMonbanを使用したアプリケーション開発で、素晴らしいスタートを切りたいのなら、[monban generators]を使用することをお勧めします。

## 使い方

Monbanは現在いくつかの革新的な期待感を持っているが、しかしあなたはこれらのいくつかを変更することができます:

- デフォルトでは`User`モデルと呼ばれている
- Monbanは、あなたのuserモデルが `create`, `id`そして`find_by`に応答することを期待している
- `User`に`email` と `password_digest` カラムを持っている
- パスワードはBCryptで管理されている


### 提案

#### Console上の使い方

もしあなたがConsole上でユーザー登録をしようとした場合に、Userモデルはパスワードを暗号化する方法を知らないため、User#newやUser#createを呼び出すことはできません。ユーザーを作成する際は、代わりに `sign_up_service`を使用してください:

```ruby
Monban.config.sign_up_service.new(email: "foo@example.com", password: "password").perform
```

#### バリデーション

Monbanは、あなたが[monban generators]を使用していない限り、あなたのuserモデルにバリデーションを追加しません。ですので、以下のようなバリデーションを追加することをオススメします:

```ruby
validates :email, presence: true, uniqueness: true
validates :password_digest, presence: true
```

加えて`config/locale/en.yml`に以下を追加することで:

```yaml
en:
  activerecord:
    attributes:
      user:
        password_digest: "Password"
```

`Password digest can't be blank` の代わりに`Password can't be blank` というエラーメッセーを生成することができます。

#### レイアウト変更

あなたのアプリケーションレイアウトには、このように追加することをオススメします:

```erb
<% if signed_in? %>
  <%= link_to "Sign out", session_path, method: :delete %>
<% else %>
  <%= link_to "Sign in", new_session_path %>
  <%= link_to "Sign up", new_user_path %>
<% end %>
```

#### ゲストユーザー

もしユーザーが未登録の状態時にゲストオブジェクトを導入したい場合は、`ApplicationController`で Monbanの`current_user`メソッドをオーバーライドすることができます:

```ruby
def current_user
  super || Guest.new
end
```

`app/models/`内で, `Guest`クラスを定義:

```ruby
class Guest
  def name
    "Guest"
  end
end
```

[Nullオブジェクトパターン](http://robots.thoughtbot.com/handling-associations-on-null-objects)のこの記事には、これを導入すべき良い理由が説明されています。

#### ユーザー登録FlashメッセージでのI18nの使用について

許可されていないページにアクセスしようとした際に、ユーザーにサインインするように指示を伝えるためにI18nを使用したい場合は、以下の設定でできます:

```ruby
Monban.configure do |config|
  config.sign_in_notice = -> { I18n.t("sign_in_notice") }
end
```

`config/initializers/monban.rb` に保存することを推奨します。

### コントローラーに追加されるメソッド

Monbanは、以下のコントローラーメソッドを提供します:

- `sign_in(user)`
- `sign_out`
- `sign_up(user_params)`
- `authenticate(user, password)`
- `authenticate_session(session_params)`
- `reset_password(user, password)`

ヘルパー:

- `current_user`
- `signed_in?`

フィルター:

- `require_login`

### ルーティング制限

`config/routes.rb`内で、ユーザー認証については:

```ruby
require "monban/constraints/signed_in"
require "monban/constraints/signed_out"

Blog::Application.routes.draw do
  constraints Monban::Constraints::SignedIn.new do
    root "dashboards#show", as: :dashboard
  end

  constraints Monban::Constraints::SignedOut.new do
    root "landings#show"
  end
end
```

## テストでの使い方

### テストモード

Monban は以下を提供し:

```ruby
Monban.test_mode!
```

パスワードのハッシュメソッドが、BCryptを使用する代わりに、プレーンテキストが返るように変更します。これにより、factoriesでpassword_digestフィールドを書くことができます:

```ruby
FactoryGirl.define do
  factory :user do
    username 'wombat'
    password_digest 'password'
  end
end
```

### Spec helpers

テスト内で、いくつかの便利なメソッドが用意されています。セットアップするには、`rails_helper.rb`か無ければ`spec_helper.rb`に以下を追加することでできます。

```ruby
Monban.test_mode!

RSpec.configure do |config|
  config.include Monban::Test::Helpers, type: :feature
  config.after :each do
    Monban.test_reset!
  end
end
```

その後、あなたのシナリオ内でこれらの[test helpers]が使えるようになります。

```ruby
feature "A feature spec" do
  scenario "that requires login" do
    user = create(:user)
    sign_in(user)
    # do something
    sign_out
    # do something else
  end
end
```

### Monbanバックドア

裏口の掃除同様に、以下を通じてすばやくパスに訪れたり、サインインできます。

```ruby
user = create(:user)
visit dashboard_path(as: user)
```

この機能を有効にするには、`config/environments/test.rb` に以下を追加してください:

```ruby
config.middleware.insert_after Warden::Manager, Monban::BackDoor
```

If you'd like to find your User model by a field other than `id`, insert the
middleware with a block that accepts the `as` query parameter and returns an
instance of your User model:

```ruby
config.middleware.insert_after Warden::Manager, Monban::BackDoor do |user_param|
  User.find_by(username: user_param)
end
```

### Controller Specs

コントローラーテストを書くなら、ヘルパーも同様に提供されています:

```ruby
Monban.test_mode!

RSpec.configure do |config|
  config.include Monban::Test::ControllerHelpers, type: :controller
  config.after :each do
    Monban.test_reset!
  end
end
```

```ruby
require 'spec_helper'

describe ProtectedController do

  describe "GET 'index'" do
    it "returns http success when signed in" do
      user = create(:user)
      sign_in(user)
      get 'index'
      response.should be_success
    end

    it "redirects when not signed in" do
      get 'index'
      response.should be_redirect
    end
  end
end
```

## 高度な機能

### メールアドレスの代わりにユーザー名での認証

メールアドレスの代わりにユーザー名でサインインをしたい場合は、設定オプションを変更するだけです。

```ruby
# config/initializers/monban.rb
Monban.configure do |config|
  config.user_lookup_field = :username
end
```

もし[monban generators]のmonban:scaffoldを使用した場合は、メールアドレスを参照する以下４箇所を修正する必要があります。

* In SessionsController#session_params
* In UsersController#user_params
* The email form field on sessions#new
* The email form field on users#new

### 複数フィールドのユーザー認証の使用について

以下のようにして複数のフィールドを使用して、ユーザーを検索することができます:

```ruby
class SessionsController < ApplicationController
  def create
    user = authenticate_session(session_params, email_or_username: [:email, :username])

    if sign_in(user)
      redirect_to(root_path)
    else
      render :new
    end
  end

  private

  def session_params
    params.require(:session).permit(:email_or_username, :password)
  end

end
```

これは、ユーザー名かメールアドレスのどちらかを利用してログインできるようにします。

## 設定

Monban::Configurationは、Monbanの動作を変える多数のオプションを用意しています。現状変更できるオプションは以下です:

### User value

* **user_lookup_field**: (default `:email`) データベースからユーザーを参照するフィールド
* **user_token_field**: (default `:password`) フォームから送信された変換前のパスワードのフィールド
* **user_token_store_field**: (default: `:password_digest`) ユーザーのパスワードダイジェストを保存するデータベース内のフィールド
* **user_class**: (default: `'User'`) Userクラス

### サービス

* **sign_in_notice**: (default: `You must be signed in`) ユーザーがログインした時に、設定するRailsのFlash Message
* **sign_in_service**: (default: `Monban::Services::SignIn`) ユーザーログインのサービスクラス
* **sign_up_service**: (default: `Monban::Services::SignUp`) ユーザー登録のサービスクラス
* **sign_out_service**: (default: `Monban::Services::SignOut`) ユーザーログアウトのサービスクラス
* **authentication_service**: (default: `Monban::Services::Authentication`) ユーザー認証のサービスクラス
* **password_reset_service**: (default: `Monban::Services::PasswordReset`) ユーザーのパスワードリセットのサービスクラス

### Rails values

* **no_login_handler**: A before_action for rails that handles when a user is not signed in.
* **no_login_redirect**: Used by the no_login_handler to redirect the user

### メソッド

* **hashing_method**: 非暗号のパスワードをハッシュ化するメソッド
* **token_comparison**: 非暗号と暗号化されたパスワードを比較するメソッド
* **creation_method**: ユーザー作成メソッド
* **find_method**: ユーザーを探すメソッド

### Warden Settings

* **failure_app**: Necessary for warden to work. A rack app that handles failures in authentication.

## 制限

以下はmonbanのいくつかの制限です:

- Monbanは、あなたが１つのuserモデルを持っていることを前提とする

## Contributing

1. [Fork it](https://github.com/halogenandtoast/monban/fork)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request

[monban generators]: https://github.com/halogenandtoast/monban-generators
[test helpers]: https://github.com/halogenandtoast/monban/blob/master/lib/monban/test/helpers.rb