repo_zf1/documentation/manual/ja/module_specs/Zend_Auth.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.auth.introduction">

    <title>導入</title>

    <para>
        <classname>Zend_Auth</classname> は、認証のための <acronym>API</acronym> を提供します。
        また、一般的な使用例に対応する具象認証アダプタも用意しています。
    </para>

    <para>
        <classname>Zend_Auth</classname> が扱うのはあくまでも <emphasis>認証 (authentication)</emphasis>
        であり、<emphasis>承認 (authorization)</emphasis> ではありません。
        認証 (authentication) とはつまり、あるエンティティが何者であるのかを示す
        (識別する) ことです。これを、なんらかの条件にもとづいて行います。
        承認 (authorization) とは、あるエンティティが他のエンティティに対して
        アクセスしたり何らかの操作をしたりする権限があるかどうかを判定する処理です。
        これは <classname>Zend_Auth</classname> の対象外となります。
        Zend Framework における認証やアクセス制御の詳細については、
        <link linkend="zend.acl"><classname>Zend_Acl</classname></link> を参照ください。
    </para>

    <note>
        <para>
            <classname>Zend_Auth</classname> クラスはシングルトンパターン
            (クラスのインスタンスは常にひとつだけ)
            を実装しており、静的メソッド <methodname>getInstance()</methodname> でそれを使用します。
            つまり、<emphasis>new</emphasis> 演算子や
            <emphasis>clone</emphasis> キーワードは <classname>Zend_Auth</classname>
            クラスでは動作しないということです。そのかわりに
            <methodname>Zend_Auth::getInstance()</methodname> を使用します。
        </para>
    </note>

    <sect2 id="zend.auth.introduction.adapters">

        <title>アダプタ</title>

        <para>
            <classname>Zend_Auth</classname> アダプタの使用目的は、
            <acronym>LDAP</acronym> や <acronym>RDBMS</acronym> あるいはファイル
            のような特定の型の認証サービスに対する認証を行うことです。
            アダプタによってそのオプションや挙動は大きくことなるでしょうが、
            いくつかの基本処理は、あらゆる認証アダプタで共通となります。
            たとえば認証条件 (いわゆる ID) を受け取り、
            認証サービスに対する問い合わせを行い、
            結果を返すという処理は、すべての <classname>Zend_Auth</classname> アダプタで共通です。
        </para>

        <para>
            各 <classname>Zend_Auth</classname> アダプタクラスは、<classname>Zend_Auth_Adapter_Interface</classname>
            を実装しています。このインターフェイスで定義されているメソッドが
            <methodname>authenticate()</methodname> で、アダプタクラスは
            認証クエリを実行するためにこれを実装する必要があります。
            各アダプタクラスは、<methodname>authenticate()</methodname>
            をコールする前に準備を済ませておく必要があります。
            つまり、アダプタ側で用意しなければならない機能としては
            認証条件 (ユーザ名およびパスワードなど) の取得や
            アダプタ固有のオプションの設定
            (データベースのテーブルを使用するアダプタならデータベースへの接続設定など)
            があるということです。
        </para>

        <para>
            以下にあげるのは認証アダプタのサンプルで、
            これはユーザ名とパスワードを受け取って認証を行います。
            その他の詳細、例えば認証サービスへの実際の問い合わせなどは、
            例を簡潔にするため省略しています。
        </para>

        <programlisting language="php"><![CDATA[
class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * 認証用のユーザ名とパスワードを設定します
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * 認証を試みます
     *
     * @throws Zend_Auth_Adapter_Exception が、認証処理をできなかった場合に発生します
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}
]]></programlisting>

        <para>
            docblock コメントで説明しているとおり、
            <methodname>authenticate()</methodname> は
            <classname>Zend_Auth_Result</classname> (あるいは <classname>Zend_Auth_Result</classname> の派生クラス)
            のインスタンスを返す必要があります。何らかの理由で認証の問い合わせができなかった場合は、
            <methodname>authenticate()</methodname> は
            <classname>Zend_Auth_Adapter_Exception</classname>
            から派生した例外をスローしなければなりません。
        </para>

    </sect2>

    <sect2 id="zend.auth.introduction.results">

        <title>結果</title>

        <para>
            <classname>Zend_Auth</classname> アダプタは、<methodname>authenticate()</methodname> の結果として
            <classname>Zend_Auth_Result</classname> のインスタンスを返します。
            これにより、認証を試みた結果を表します。アダプタのインスタンスを作成した際に
            <classname>Zend_Auth_Result</classname> オブジェクトが作成され、
            以下の 4 つのメソッドで <classname>Zend_Auth</classname> アダプタの結果に対する共通の操作ができます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>isValid()</methodname> - その結果が
                    認証の成功を表している場合にのみ <constant>TRUE</constant> を返します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getCode()</methodname> - <classname>Zend_Auth_Result</classname> の定数を返します。
                    これは、認証に失敗したのか成功したのかを表すものです。
                    これを使用する場面としては、認証の結果をいくつかの結果から区別したい場合などがあります。
                    これにより、たとえば認証結果について、より詳細な情報を管理することができるようになります。
                    別の使用法としては、ユーザに示すメッセージを変更し、より詳細な情報を伝えられるようにすることなどがあります。
                    しかし、一般的な「認証失敗」メッセージではなく
                    ユーザに対して詳細な情報を示す際には、そのリスクを知っておくべきです。
                    詳細な情報は、以下の注意を参照ください。
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getIdentity()</methodname> - 認証を試みた ID 情報を返します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getMessages()</methodname> - 認証に失敗した場合に、
                    関連するメッセージの配列を返します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            認証の結果によって処理を分岐させ、より決め細やかな処理を行いたいこともあるでしょう。
            有用な処理としては、たとえば間違ったパスワードを繰り返し入力したアカウントをロックしたり、
            存在しない ID を何度も入力した IP アドレスに印をつけたり、
            ユーザに対してよりわかりやすいメッセージを返したりといったことがあります。
            次の結果コードが使用可能です。
        </para>

        <programlisting language="php"><![CDATA[
Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED
]]></programlisting>

        <para>
            次の例は、結果コードを処理する方法を示すものです。
        </para>

        <programlisting language="php"><![CDATA[
// AuthController / loginAction の中の処理
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** ID が存在しない場合の処理 **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** 認証に失敗した場合の処理 **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** 認証に成功した場合の処理 **/
        break;

    default:
        /** その他の原因で失敗した場合の処理 **/
        break;
}
]]></programlisting>

    </sect2>

    <sect2 id="zend.auth.introduction.persistence">

        <title>ID の永続性</title>

        <para>
            認証情報 (パスワードなど) を含む認証を要求するのは便利なものですが、
            リクエストごとにいちいち認証情報を引き回すのではなく、
            認証済みの ID を保持し続けることも重要です。
        </para>

        <para>
            <acronym>HTTP</acronym> はステートレスなプロトコルです。しかし、
            クッキーやセッションといった技術によって、
            サーバサイドのウェブアプリケーションでも
            複数リクエスト間でステート (状態) を保持し続けられるようになりました。
        </para>

        <sect3 id="zend.auth.introduction.persistence.default">

            <title>PHP セッションにおけるデフォルトの持続性</title>

            <para>
                 デフォルトでは、<classname>Zend_Auth</classname> は、
                 認証に成功した際の ID 情報を <acronym>PHP</acronym> のセッションを使用して保存します。
                 認証に成功すると、<methodname>Zend_Auth::authenticate()</methodname>
                 は認証結果を持続ストレージに保存します。何も指定しなければ、
                 <classname>Zend_Auth</classname> が使用するストレージクラスは
                 <classname>Zend_Auth_Storage_Session</classname> となります。これは
                 <link linkend="zend.session"><classname>Zend_Session</classname></link> を使用しています。
                 独自のクラスを使用するには、<classname>Zend_Auth_Storage_Interface</classname>
                 を実装したクラスのオブジェクトを <methodname>Zend_Auth::setStorage()</methodname>
                 で設定します。
            </para>

            <note>
                <para>
                    もし ID が自動的に持続ストレージに保存されるのが気に入らない場合は、
                    <classname>Zend_Auth</classname> クラスをまるごと使用するのを控え、
                    アダプタクラスを直接使用します。
                </para>
            </note>

            <example id="zend.auth.introduction.persistence.default.example">

                <title>セッション名前空間の変更</title>

                <para>
                    <classname>Zend_Auth_Storage_Session</classname> は、セッション名前空間として
                    '<classname>Zend_Auth</classname>' を使用します。これを変更するには、別の値を
                    <classname>Zend_Auth_Storage_Session</classname> のコンストラクタで指定します。
                    この値が、内部で <classname>Zend_Session_Namespace</classname>
                    のコンストラクタに渡されます。これは認証を試みる前に行う必要があります。
                    なぜなら、<methodname>Zend_Auth::authenticate()</methodname>
                    は ID を自動的に保存するからです。
                </para>

                <programlisting language="php"><![CDATA[
// Zend_Auth のシングルトンインスタンスへの参照を保存します
$auth = Zend_Auth::getInstance();

// 'Zend_Auth' のかわりに 'someNamespace' を使用します
$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));

/**
 * @todo 認証アダプタ $authAdapter を設定します
 */

// 認証と結果の保存、そして成功時に ID を持続させます
$result = $auth->authenticate($authAdapter);
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.auth.introduction.persistence.custom">

            <title>独自のストレージの実装</title>

            <para>
                <classname>Zend_Auth_Storage_Session</classname> とは異なる形式で、
                ID を持続させたくなることもあるでしょう。そのような場合は、
                <classname>Zend_Auth_Storage_Interface</classname> を実装したクラスのインスタンスを
                <methodname>Zend_Auth::setStorage()</methodname> で設定します。
            </para>

            <example id="zend.auth.introduction.persistence.custom.example">

                <title>独自のストレージクラスの使用法</title>

                <para>
                    ID を持続させるストレージクラスを
                    <classname>Zend_Auth_Storage_Session</classname> の代わりに使用するには、
                    <classname>Zend_Auth_Storage_Interface</classname> を実装します。
                </para>

                <programlisting language="php"><![CDATA[
class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * ストレージが空の場合にのみ true を返す
     *
     * @throws Zend_Auth_Storage_Exception 空かどうか判断できないとき
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * ストレージの中身を返す
     *
     * ストレージが空の場合に挙動は未定義
     *
     * @throws Zend_Auth_Storage_Exception ストレージの中身を読み込めない場合
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * $contents をストレージに書き込む
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception $contents をストレージに書き込めない場合
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * ストレージの中身を消去する
     *
     * @throws Zend_Auth_Storage_Exception ストレージの中身を消去できない場合
     * @return void
     */
    public function clear()
    {
        /**
         * @todo 実装が必要
         */
    }
}
]]></programlisting>

                <para>
                    このストレージクラスを使用するには、認証クエリの前に
                    <methodname>Zend_Auth::setStorage()</methodname> を実行します。
                </para>

                <programlisting language="php"><![CDATA[
// Zend_Auth に、独自のストレージクラスを使うよう指示します
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @todo 認証アダプタ $authAdapter を設定します
 */

// 認証と結果の保存、そして成功時に ID を持続させます
$result = Zend_Auth::getInstance()->authenticate($authAdapter);
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.auth.introduction.using">

        <title>使用法</title>

        <para>
            <classname>Zend_Auth</classname> の使用法には、次の二通りがあります。
        </para>

        <orderedlist>
            <listitem>
                <para>
                    間接的に <methodname>Zend_Auth::authenticate()</methodname> 経由で使用する
                </para>
            </listitem>
            <listitem>
                <para>
                    直接、アダプタの <methodname>authenticate()</methodname> メソッドを使用する
                </para>
            </listitem>
        </orderedlist>

        <para>
            次の例は、<classname>Zend_Auth</classname> アダプタを間接的に
            <classname>Zend_Auth</classname> クラスから使用するものです。
        </para>

        <programlisting language="php"><![CDATA[
// Zend_Auth のシングルトンインスタンスへの参照を取得します
$auth = Zend_Auth::getInstance();

// 認証アダプタを設定します
$authAdapter = new MyAuthAdapter($username, $password);

// 認証を試み、その結果を取得します
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // 認証に失敗したので、原因を表示します
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // 認証に成功しました。ID ($username) がセッションに保存されます
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}
]]></programlisting>

        <para>
            上の例においてリクエスト内で認証が行われると、
            認証に成功した際にその ID を取得するのは簡単なことです。
        </para>

        <programlisting language="php"><![CDATA[
$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // ID があるのでそれを取得します
    $identity = $auth->getIdentity();
}
]]></programlisting>

        <para>
            永続ストレージから認証 ID を削除するには、単純に
            <methodname>clearIdentity()</methodname> メソッドを使用します。
            これは、アプリケーションの "ログアウト" 処理を実装するためのものです。
        </para>

        <programlisting language="php"><![CDATA[
Zend_Auth::getInstance()->clearIdentity();
]]></programlisting>

        <para>
            自動的に永続ストレージが用いられるのがまずい場合もあるでしょう。
            そんな場合は、<classname>Zend_Auth</classname> クラスをバイパスして
            アダプタクラスを直接使用します。
            アダプタクラスを直接使用するとは、アダプタオブジェクトの設定と準備を行い、
            その <methodname>authenticate()</methodname> メソッドをコールするということです。
            アダプタ固有の詳細情報については、各アダプタのドキュメントで説明します。
            以下の例は、<classname>MyAuthAdapter</classname> を直接使用するものです。
        </para>

        <programlisting language="php"><![CDATA[
// 認証アダプタを設定します
$authAdapter = new MyAuthAdapter($username, $password);

// 認証を試み、その結果を取得します
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // 認証に失敗したので、原因を表示します
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // 認証に成功しました
    // $result->getIdentity() === $username
}
]]></programlisting>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->