<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17175 -->
<sect1 id="zend.auth.adapter.dbtable">
    <title>データベースのテーブルでの認証</title>
    <sect2 id="zend.auth.adapter.dbtable.introduction">
        <title>導入</title>
        <para>
            <classname>Zend_Auth_Adapter_DbTable</classname> は、
            データベースのテーブルに保存された証明情報に基づいた認証の機能を提供します。
            <classname>Zend_Auth_Adapter_DbTable</classname> のコンストラクタには
            <classname>Zend_Db_Adapter_Abstract</classname> のインスタンスを渡す必要があるので、
            各インスタンスは特定のデータベース接続に関連付けられます。
            コンストラクタではその他の設定オプションも指定することができます。
            これらは個別にインスタンスメソッドで指定することもできます。
        </para>

        <para>
            次のような設定オプションが使用可能です。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>tableName</property></emphasis>:
                    これはデータベースのテーブル名です。証明情報が含まれ、
                    認証クエリの問い合わせ先となるテーブル名を指定します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><property>identityColumn</property></emphasis>:
                    これは、ID を表すデータベーステーブルのカラム名です。
                    このカラムには、ユーザ名やメールアドレスのような一意な値が含まれている必要があります。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><property>credentialColumn</property></emphasis>:
                    これは、証明情報を表すデータベーステーブルのカラム名です。
                    単純な ID およびパスワードによる認証方式では、この値がパスワードに対応します。
                    <property>credentialTreatment</property> オプションも参照ください。
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis><property>credentialTreatment</property></emphasis>:
                    多くの場合、パスワードやその他機密情報は、何らかの関数やアルゴリズムで
                    暗号化、ハッシュ化、符号化、ぼかしなどの処理が行われています。
                    これらの処理を表すパラメータつきの文字列、たとえば
                    '<methodname>MD5(?)</methodname>' や
                    '<methodname>PASSWORD(?)</methodname>'
                    を指定することで、
                    証明データに対して任意の <acronym>SQL</acronym> を適用できるようになります。
                    これらの関数は <acronym>RDBMS</acronym> によって異なります。
                    データベースシステムでどのような関数が使えるのかについては、
                    データベースのマニュアルをご確認ください。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.auth.adapter.dbtable.introduction.example.basic_usage">
            <title>基本的な使用法</title>
            <para>
                導入部で説明したとおり、<classname>Zend_Auth_Adapter_DbTable</classname>
                のコンストラクタには <classname>Zend_Db_Adapter_Abstract</classname>
                のインスタンスを渡す必要があります。これは、認証アダプタのインスタンスと
                関連付けるデータベース接続を表します。
                まず、データベース接続を作成する必要があります。
            </para>

            <para>
                次のコードは、メモリ内データベースのアダプタを作成し、
                簡単なテーブルスキーマを作成し、そして後で認証クエリを実行するための行を追加します。
                この例を実行するには、<acronym>PDO</acronym> SQLite 拡張モジュールが有効になっている必要があります。
            </para>

            <programlisting language="php"><![CDATA[
// メモリ内で SQLite データベース接続を作成します
$dbAdapter = new Zend_Db_Adapter_Pdo_Sqlite(array('dbname' =>
                                                  ':memory:'));

// 単純なテーブルを作成するクエリ
$sqlCreate = 'CREATE TABLE [users] ('
           . '[id] INTEGER  NOT NULL PRIMARY KEY, '
           . '[username] VARCHAR(50) UNIQUE NOT NULL, '
           . '[password] VARCHAR(32) NULL, '
           . '[real_name] VARCHAR(150) NULL)';

// 認証情報テーブルを作成します
$dbAdapter->query($sqlCreate);

// 認証を成功させるために行を追加します
$sqlInsert = "INSERT INTO users (username, password, real_name) "
           . "VALUES ('my_username', 'my_password', 'My Real Name')";

// データを挿入します
$dbAdapter->query($sqlInsert);]]></programlisting>

            <para>
                データベース接続およびテーブルが使用可能となったので
                <classname>Zend_Auth_Adapter_DbTable</classname> のインスタンスが作成できます。
                設定オプションの値は、コンストラクタで渡すか、
                あるいはインスタンスを作成した後に設定用メソッドで指定します。
            </para>

            <programlisting language="php"><![CDATA[
// コンストラクタにパラメータを渡し、インスタンスを設定します
$authAdapter = new Zend_Auth_Adapter_DbTable(
    $dbAdapter,
    'users',
    'username',
    'password'
);

// あるいは、設定用メソッドでインスタンスの設定を行います
$authAdapter = new Zend_Auth_Adapter_DbTable($dbAdapter);

$authAdapter
    ->setTableName('users')
    ->setIdentityColumn('username')
    ->setCredentialColumn('password')
;]]></programlisting>
            <para>
                この時点で、認証アダプタのインスタンスは認証クエリを受け付ける準備ができました。
                認証クエリを処理するには、入力された証明情報をアダプタに渡してから
                <methodname>authenticate()</methodname> メソッドをコールします。
            </para>

            <programlisting language="php"><![CDATA[
// 入力情報 (ログインフォームからの値など) を設定します
$authAdapter
    ->setIdentity('my_username')
    ->setCredential('my_password')
;

// 認証クエリを実行し、結果を保存します
]]></programlisting>

            <para>
                認証結果オブジェクトでの <methodname>getIdentity()</methodname>
                メソッドに加え、<classname>Zend_Auth_Adapter_DbTable</classname>
                は認証の成功時にテーブルの行を取得する機能もサポートしています。
            </para>

            <programlisting language="php"><![CDATA[
// ID を表示します
echo $result->getIdentity() . "\n\n";

// 結果の行を表示します
print_r($authAdapter->getResultRowObject());

/* 出力結果
my_username

Array
(
    [id] => 1
    [username] => my_username
    [password] => my_password
    [real_name] => My Real Name
)
*/]]></programlisting>
            <para>
                テーブルの行には証明情報が含まれているので、
                予期せぬアクセスからその内容を守ることが重要となります。
            </para>
        </example>
    </sect2>
    <sect2 id="zend.auth.adapter.dbtable.advanced.storing_result_row">
        <title>応用例: 持続的な DbTable 結果オブジェクト</title>
        <para>
            デフォルトでは <classname>Zend_Auth_Adapter_DbTable</classname> は、
            認証に成功した際に認証情報を返します。場合によっては、
            <classname>Zend_Auth</classname> の持続ストレージの仕組みを利用して
            別の有用な情報を格納したいこともあるでしょう。その場合は、
            <methodname>getResultRowObject()</methodname> メソッドを使用して
            <emphasis>stdClass</emphasis> オブジェクトを返します。
            次のコードで、使用法をご確認ください。
        </para>
        <programlisting language="php"><![CDATA[
// Zend_Auth_Adapter_DbTable による認証を行います
$result = $this->_auth->authenticate($adapter);

if ($result->isValid()) {
    // 認証情報をオブジェクトとして保存し、username と real_name のみを返します
    $storage = $this->_auth->getStorage();
    $storage->write($adapter->getResultRowObject(array(
        'username',
        'real_name',
    )));

    // 認証情報をオブジェクトとして保存し、password のみを省略します
    $storage->write($adapter->getResultRowObject(
        null,
        'password'
    ));

    /* ... */

} else {

    /* ... */

}]]></programlisting>
    </sect2>
    <sect2 id="zend.auth.adapter.dbtable.advanced.advanced_usage">
        <title>高度な使用例</title>
        <para>
            <classname>Zend_Auth</classname> (そして <classname>Zend_Auth_Adapter_DbTable</classname>) の主な目的は
            <emphasis>認証 (authentication)</emphasis> であって
            <emphasis>認可 (authorization)</emphasis>,
            ではありませんが、認可にもかかわる問題も多少あります。
            問題によっては、認証アダプタの中で認可にかかわる問題を解決することもあるでしょう。
        </para>
        <para>
            ちょっとしたおまけとして <classname>Zend_Auth_Adapter_DbTable</classname>
            に組み込まれている仕組みを使用すると、
            認証時にありがちな問題を解決するチェックを加えることができます。
        </para>
        <programlisting language="php"><![CDATA[
// アカウントの status フィールドが "compromised" ではない
$adapter = new Zend_Auth_Adapter_DbTable(
    $db,
    'users',
    'username',
    'password',
    'MD5(?) AND status != "compromised"'
);

// アカウントの active フィールドが "TRUE" に等しい
$adapter = new Zend_Auth_Adapter_DbTable(
    $db,
    'users',
    'username',
    'password',
    'MD5(?) AND active = "TRUE"'
);]]></programlisting>
        <para>
            もうひとつの例として、salt メカニズムの実装を見てみましょう。
            salt とは、アプリケーションのセキュリティを格段に向上させるテクニックを指す用語です。
            パスワードにランダムな文字列を連結することで、
            辞書を用いた総当たり攻撃からパスワードを保護するという仕組みになっています。
        </para>
        <para>
            salt 文字列を格納するために、テーブルの構造を変更する必要があります。
        </para>
        <programlisting language="php"><![CDATA[
$sqlAlter = "ALTER TABLE [users] "
          . "ADD COLUMN [password_salt] "
          . "AFTER [password]";

$dbAdapter->query($sqlAlter);]]></programlisting>
        <para>
            すべてのユーザに対して登録時に salt 文字列を生成するシンプルな方法を示します。
        </para>
        <programlisting language="php"><![CDATA[
for ($i = 0; $i < 50; $i++) {
    $dynamicSalt .= chr(rand(33, 126));
}]]></programlisting>
        <para>
            それではアダプタを作成してみましょう。
        </para>
        <programlisting language="php"><![CDATA[
$adapter = new Zend_Auth_Adapter_DbTable(
    $db,
    'users',
    'username',
    'password',
    "MD5(CONCAT('"
    . Zend_Registry::get('staticSalt')
    . "', ?, password_salt))"
);]]></programlisting>
        <note>
            <para>
                salt がたとえハードコーディングされた固定文字列であったとしても、
                セキュリティを向上させることができます。
                仮に (<acronym>SQL</acronym> インジェクション攻撃などで) データベースに侵入されたとしても、
                ウェブサーバは無傷なのでデータを攻撃者に悪用されることはありません。
            </para>
        </note>
        <para>
            もうひとつの方法は、アダプタを作成したあとで <classname>Zend_Auth_Adapter_DbTable</classname>
            の <methodname>getDbSelect()</methodname> メソッドを使うことです。
            このメソッドが返す <classname>Zend_Db_Select</classname> オブジェクトのインスタンスで
            <methodname>authenticate()</methodname> を実行します。このメソッドは、<methodname>authenticate()</methodname>
            をコールしたかどうかにかかわらず同じオブジェクトを返すことに注意しましょう。
            このオブジェクトには識別や認証のための情報は含まれておらず、
            <methodname>authenticate()</methodname> によってそれらが組み込まれます。
        </para>
        <para>
            <methodname>getDbSelect()</methodname> メソッドを使いたくなるひとつの例としては、
            たとえばユーザの状態のチェック、
            つまりそのユーザアカウントが有効になっているかどうかの確認などがあります。
        </para>
        <programlisting language="php"><![CDATA[
// 上の例の続き
$adapter = new Zend_Auth_Adapter_DbTable(
    $db,
    'users',
    'username',
    'password',
    'MD5(?)'
);

// select オブジェクトを (参照として) 取得します
$select = $adapter->getDbSelect();
$select->where('active = "TRUE"');

// 認証。これにより、users.active = TRUE であることを保証します
$adapter->authenticate();

]]></programlisting>
    </sect2>
</sect1>
