documentation/manual/ja/module_specs/Zend_Auth.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20763 -->
   4 <sect1 id="zend.auth.introduction">
   5
   6     <title>導入</title>
   7
   8     <para>
   9         <classname>Zend_Auth</classname> は、認証のための <acronym>API</acronym> を提供します。
  10         また、一般的な使用例に対応する具象認証アダプタも用意しています。
  11     </para>
  12
  13     <para>
  14         <classname>Zend_Auth</classname> が扱うのはあくまでも <emphasis>認証 (authentication)</emphasis>
  15         であり、<emphasis>承認 (authorization)</emphasis> ではありません。
  16         認証 (authentication) とはつまり、あるエンティティが何者であるのかを示す
  17         (識別する) ことです。これを、なんらかの条件にもとづいて行います。
  18         承認 (authorization) とは、あるエンティティが他のエンティティに対して
  19         アクセスしたり何らかの操作をしたりする権限があるかどうかを判定する処理です。
  20         これは <classname>Zend_Auth</classname> の対象外となります。
  21         Zend Framework における認証やアクセス制御の詳細については、
  22         <link linkend="zend.acl"><classname>Zend_Acl</classname></link> を参照ください。
  23     </para>
  24
  25     <note>
  26         <para>
  27             <classname>Zend_Auth</classname> クラスはシングルトンパターン
  28             (クラスのインスタンスは常にひとつだけ)
  29             を実装しており、静的メソッド <methodname>getInstance()</methodname> でそれを使用します。
  30             つまり、<emphasis>new</emphasis> 演算子や
  31             <emphasis>clone</emphasis> キーワードは <classname>Zend_Auth</classname>
  32             クラスでは動作しないということです。そのかわりに
  33             <methodname>Zend_Auth::getInstance()</methodname> を使用します。
  34         </para>
  35     </note>
  36
  37     <sect2 id="zend.auth.introduction.adapters">
  38
  39         <title>アダプタ</title>
  40
  41         <para>
  42             <classname>Zend_Auth</classname> アダプタの使用目的は、
  43             <acronym>LDAP</acronym> や <acronym>RDBMS</acronym> あるいはファイル
  44             のような特定の型の認証サービスに対する認証を行うことです。
  45             アダプタによってそのオプションや挙動は大きくことなるでしょうが、
  46             いくつかの基本処理は、あらゆる認証アダプタで共通となります。
  47             たとえば認証条件 (いわゆる ID) を受け取り、
  48             認証サービスに対する問い合わせを行い、
  49             結果を返すという処理は、すべての <classname>Zend_Auth</classname> アダプタで共通です。
  50         </para>
  51
  52         <para>
  53             各 <classname>Zend_Auth</classname> アダプタクラスは、<classname>Zend_Auth_Adapter_Interface</classname>
  54             を実装しています。このインターフェイスで定義されているメソッドが
  55             <methodname>authenticate()</methodname> で、アダプタクラスは
  56             認証クエリを実行するためにこれを実装する必要があります。
  57             各アダプタクラスは、<methodname>authenticate()</methodname>
  58             をコールする前に準備を済ませておく必要があります。
  59             つまり、アダプタ側で用意しなければならない機能としては
  60             認証条件 (ユーザ名およびパスワードなど) の取得や
  61             アダプタ固有のオプションの設定
  62             (データベースのテーブルを使用するアダプタならデータベースへの接続設定など)
  63             があるということです。
  64         </para>
  65
  66         <para>
  67             以下にあげるのは認証アダプタのサンプルで、
  68             これはユーザ名とパスワードを受け取って認証を行います。
  69             その他の詳細、例えば認証サービスへの実際の問い合わせなどは、
  70             例を簡潔にするため省略しています。
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 class MyAuthAdapter implements Zend_Auth_Adapter_Interface
  75 {
  76     /**
  77      * 認証用のユーザ名とパスワードを設定します
  78      *
  79      * @return void
  80      */
  81     public function __construct($username, $password)
  82     {
  83         // ...
  84     }
  85
  86     /**
  87      * 認証を試みます
  88      *
  89      * @throws Zend_Auth_Adapter_Exception が、認証処理をできなかった場合に発生します
  90      * @return Zend_Auth_Result
  91      */
  92     public function authenticate()
  93     {
  94         // ...
  95     }
  96 }
  97 ]]></programlisting>
  98
  99         <para>
 100             docblock コメントで説明しているとおり、
 101             <methodname>authenticate()</methodname> は
 102             <classname>Zend_Auth_Result</classname> (あるいは <classname>Zend_Auth_Result</classname> の派生クラス)
 103             のインスタンスを返す必要があります。何らかの理由で認証の問い合わせができなかった場合は、
 104             <methodname>authenticate()</methodname> は
 105             <classname>Zend_Auth_Adapter_Exception</classname>
 106             から派生した例外をスローしなければなりません。
 107         </para>
 108
 109     </sect2>
 110
 111     <sect2 id="zend.auth.introduction.results">
 112
 113         <title>結果</title>
 114
 115         <para>
 116             <classname>Zend_Auth</classname> アダプタは、<methodname>authenticate()</methodname> の結果として
 117             <classname>Zend_Auth_Result</classname> のインスタンスを返します。
 118             これにより、認証を試みた結果を表します。アダプタのインスタンスを作成した際に
 119             <classname>Zend_Auth_Result</classname> オブジェクトが作成され、
 120             以下の 4 つのメソッドで <classname>Zend_Auth</classname> アダプタの結果に対する共通の操作ができます。
 121         </para>
 122
 123         <itemizedlist>
 124             <listitem>
 125                 <para>
 126                     <methodname>isValid()</methodname> - その結果が
 127                     認証の成功を表している場合にのみ <constant>TRUE</constant> を返します。
 128                 </para>
 129             </listitem>
 130             <listitem>
 131                 <para>
 132                     <methodname>getCode()</methodname> - <classname>Zend_Auth_Result</classname> の定数を返します。
 133                     これは、認証に失敗したのか成功したのかを表すものです。
 134                     これを使用する場面としては、認証の結果をいくつかの結果から区別したい場合などがあります。
 135                     これにより、たとえば認証結果について、より詳細な情報を管理することができるようになります。
 136                     別の使用法としては、ユーザに示すメッセージを変更し、より詳細な情報を伝えられるようにすることなどがあります。
 137                     しかし、一般的な「認証失敗」メッセージではなく
 138                     ユーザに対して詳細な情報を示す際には、そのリスクを知っておくべきです。
 139                     詳細な情報は、以下の注意を参照ください。
 140                 </para>
 141             </listitem>
 142             <listitem>
 143                 <para>
 144                     <methodname>getIdentity()</methodname> - 認証を試みた ID 情報を返します。
 145                 </para>
 146             </listitem>
 147             <listitem>
 148                 <para>
 149                     <methodname>getMessages()</methodname> - 認証に失敗した場合に、
 150                     関連するメッセージの配列を返します。
 151                 </para>
 152             </listitem>
 153         </itemizedlist>
 154
 155         <para>
 156             認証の結果によって処理を分岐させ、より決め細やかな処理を行いたいこともあるでしょう。
 157             有用な処理としては、たとえば間違ったパスワードを繰り返し入力したアカウントをロックしたり、
 158             存在しない ID を何度も入力した IP アドレスに印をつけたり、
 159             ユーザに対してよりわかりやすいメッセージを返したりといったことがあります。
 160             次の結果コードが使用可能です。
 161         </para>
 162
 163         <programlisting language="php"><![CDATA[
 164 Zend_Auth_Result::SUCCESS
 165 Zend_Auth_Result::FAILURE
 166 Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
 167 Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
 168 Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
 169 Zend_Auth_Result::FAILURE_UNCATEGORIZED
 170 ]]></programlisting>
 171
 172         <para>
 173             次の例は、結果コードを処理する方法を示すものです。
 174         </para>
 175
 176         <programlisting language="php"><![CDATA[
 177 // AuthController / loginAction の中の処理
 178 $result = $this->_auth->authenticate($adapter);
 179
 180 switch ($result->getCode()) {
 181
 182     case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
 183         /** ID が存在しない場合の処理 **/
 184         break;
 185
 186     case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
 187         /** 認証に失敗した場合の処理 **/
 188         break;
 189
 190     case Zend_Auth_Result::SUCCESS:
 191         /** 認証に成功した場合の処理 **/
 192         break;
 193
 194     default:
 195         /** その他の原因で失敗した場合の処理 **/
 196         break;
 197 }
 198 ]]></programlisting>
 199
 200     </sect2>
 201
 202     <sect2 id="zend.auth.introduction.persistence">
 203
 204         <title>ID の永続性</title>
 205
 206         <para>
 207             認証情報 (パスワードなど) を含む認証を要求するのは便利なものですが、
 208             リクエストごとにいちいち認証情報を引き回すのではなく、
 209             認証済みの ID を保持し続けることも重要です。
 210         </para>
 211
 212         <para>
 213             <acronym>HTTP</acronym> はステートレスなプロトコルです。しかし、
 214             クッキーやセッションといった技術によって、
 215             サーバサイドのウェブアプリケーションでも
 216             複数リクエスト間でステート (状態) を保持し続けられるようになりました。
 217         </para>
 218
 219         <sect3 id="zend.auth.introduction.persistence.default">
 220
 221             <title>PHP セッションにおけるデフォルトの持続性</title>
 222
 223             <para>
 224                  デフォルトでは、<classname>Zend_Auth</classname> は、
 225                  認証に成功した際の ID 情報を <acronym>PHP</acronym> のセッションを使用して保存します。
 226                  認証に成功すると、<methodname>Zend_Auth::authenticate()</methodname>
 227                  は認証結果を持続ストレージに保存します。何も指定しなければ、
 228                  <classname>Zend_Auth</classname> が使用するストレージクラスは
 229                  <classname>Zend_Auth_Storage_Session</classname> となります。これは
 230                  <link linkend="zend.session"><classname>Zend_Session</classname></link> を使用しています。
 231                  独自のクラスを使用するには、<classname>Zend_Auth_Storage_Interface</classname>
 232                  を実装したクラスのオブジェクトを <methodname>Zend_Auth::setStorage()</methodname>
 233                  で設定します。
 234             </para>
 235
 236             <note>
 237                 <para>
 238                     もし ID が自動的に持続ストレージに保存されるのが気に入らない場合は、
 239                     <classname>Zend_Auth</classname> クラスをまるごと使用するのを控え、
 240                     アダプタクラスを直接使用します。
 241                 </para>
 242             </note>
 243
 244             <example id="zend.auth.introduction.persistence.default.example">
 245
 246                 <title>セッション名前空間の変更</title>
 247
 248                 <para>
 249                     <classname>Zend_Auth_Storage_Session</classname> は、セッション名前空間として
 250                     '<classname>Zend_Auth</classname>' を使用します。これを変更するには、別の値を
 251                     <classname>Zend_Auth_Storage_Session</classname> のコンストラクタで指定します。
 252                     この値が、内部で <classname>Zend_Session_Namespace</classname>
 253                     のコンストラクタに渡されます。これは認証を試みる前に行う必要があります。
 254                     なぜなら、<methodname>Zend_Auth::authenticate()</methodname>
 255                     は ID を自動的に保存するからです。
 256                 </para>
 257
 258                 <programlisting language="php"><![CDATA[
 259 // Zend_Auth のシングルトンインスタンスへの参照を保存します
 260 $auth = Zend_Auth::getInstance();
 261
 262 // 'Zend_Auth' のかわりに 'someNamespace' を使用します
 263 $auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));
 264
 265 /**
 266  * @todo 認証アダプタ $authAdapter を設定します
 267  */
 268
 269 // 認証と結果の保存、そして成功時に ID を持続させます
 270 $result = $auth->authenticate($authAdapter);
 271 ]]></programlisting>
 272
 273             </example>
 274
 275         </sect3>
 276
 277         <sect3 id="zend.auth.introduction.persistence.custom">
 278
 279             <title>独自のストレージの実装</title>
 280
 281             <para>
 282                 <classname>Zend_Auth_Storage_Session</classname> とは異なる形式で、
 283                 ID を持続させたくなることもあるでしょう。そのような場合は、
 284                 <classname>Zend_Auth_Storage_Interface</classname> を実装したクラスのインスタンスを
 285                 <methodname>Zend_Auth::setStorage()</methodname> で設定します。
 286             </para>
 287
 288             <example id="zend.auth.introduction.persistence.custom.example">
 289
 290                 <title>独自のストレージクラスの使用法</title>
 291
 292                 <para>
 293                     ID を持続させるストレージクラスを
 294                     <classname>Zend_Auth_Storage_Session</classname> の代わりに使用するには、
 295                     <classname>Zend_Auth_Storage_Interface</classname> を実装します。
 296                 </para>
 297
 298                 <programlisting language="php"><![CDATA[
 299 class MyStorage implements Zend_Auth_Storage_Interface
 300 {
 301     /**
 302      * ストレージが空の場合にのみ true を返す
 303      *
 304      * @throws Zend_Auth_Storage_Exception 空かどうか判断できないとき
 305      * @return boolean
 306      */
 307     public function isEmpty()
 308     {
 309         /**
 310          * @todo 実装が必要
 311          */
 312     }
 313
 314     /**
 315      * ストレージの中身を返す
 316      *
 317      * ストレージが空の場合に挙動は未定義
 318      *
 319      * @throws Zend_Auth_Storage_Exception ストレージの中身を読み込めない場合
 320      * @return mixed
 321      */
 322     public function read()
 323     {
 324         /**
 325          * @todo 実装が必要
 326          */
 327     }
 328
 329     /**
 330      * $contents をストレージに書き込む
 331      *
 332      * @param  mixed $contents
 333      * @throws Zend_Auth_Storage_Exception $contents をストレージに書き込めない場合
 334      * @return void
 335      */
 336     public function write($contents)
 337     {
 338         /**
 339          * @todo 実装が必要
 340          */
 341     }
 342
 343     /**
 344      * ストレージの中身を消去する
 345      *
 346      * @throws Zend_Auth_Storage_Exception ストレージの中身を消去できない場合
 347      * @return void
 348      */
 349     public function clear()
 350     {
 351         /**
 352          * @todo 実装が必要
 353          */
 354     }
 355 }
 356 ]]></programlisting>
 357
 358                 <para>
 359                     このストレージクラスを使用するには、認証クエリの前に
 360                     <methodname>Zend_Auth::setStorage()</methodname> を実行します。
 361                 </para>
 362
 363                 <programlisting language="php"><![CDATA[
 364 // Zend_Auth に、独自のストレージクラスを使うよう指示します
 365 Zend_Auth::getInstance()->setStorage(new MyStorage());
 366
 367 /**
 368  * @todo 認証アダプタ $authAdapter を設定します
 369  */
 370
 371 // 認証と結果の保存、そして成功時に ID を持続させます
 372 $result = Zend_Auth::getInstance()->authenticate($authAdapter);
 373 ]]></programlisting>
 374
 375             </example>
 376
 377         </sect3>
 378
 379     </sect2>
 380
 381     <sect2 id="zend.auth.introduction.using">
 382
 383         <title>使用法</title>
 384
 385         <para>
 386             <classname>Zend_Auth</classname> の使用法には、次の二通りがあります。
 387         </para>
 388
 389         <orderedlist>
 390             <listitem>
 391                 <para>
 392                     間接的に <methodname>Zend_Auth::authenticate()</methodname> 経由で使用する
 393                 </para>
 394             </listitem>
 395             <listitem>
 396                 <para>
 397                     直接、アダプタの <methodname>authenticate()</methodname> メソッドを使用する
 398                 </para>
 399             </listitem>
 400         </orderedlist>
 401
 402         <para>
 403             次の例は、<classname>Zend_Auth</classname> アダプタを間接的に
 404             <classname>Zend_Auth</classname> クラスから使用するものです。
 405         </para>
 406
 407         <programlisting language="php"><![CDATA[
 408 // Zend_Auth のシングルトンインスタンスへの参照を取得します
 409 $auth = Zend_Auth::getInstance();
 410
 411 // 認証アダプタを設定します
 412 $authAdapter = new MyAuthAdapter($username, $password);
 413
 414 // 認証を試み、その結果を取得します
 415 $result = $auth->authenticate($authAdapter);
 416
 417 if (!$result->isValid()) {
 418     // 認証に失敗したので、原因を表示します
 419     foreach ($result->getMessages() as $message) {
 420         echo "$message\n";
 421     }
 422 } else {
 423     // 認証に成功しました。ID ($username) がセッションに保存されます
 424     // $result->getIdentity() === $auth->getIdentity()
 425     // $result->getIdentity() === $username
 426 }
 427 ]]></programlisting>
 428
 429         <para>
 430             上の例においてリクエスト内で認証が行われると、
 431             認証に成功した際にその ID を取得するのは簡単なことです。
 432         </para>
 433
 434         <programlisting language="php"><![CDATA[
 435 $auth = Zend_Auth::getInstance();
 436 if ($auth->hasIdentity()) {
 437     // ID があるのでそれを取得します
 438     $identity = $auth->getIdentity();
 439 }
 440 ]]></programlisting>
 441
 442         <para>
 443             永続ストレージから認証 ID を削除するには、単純に
 444             <methodname>clearIdentity()</methodname> メソッドを使用します。
 445             これは、アプリケーションの "ログアウト" 処理を実装するためのものです。
 446         </para>
 447
 448         <programlisting language="php"><![CDATA[
 449 Zend_Auth::getInstance()->clearIdentity();
 450 ]]></programlisting>
 451
 452         <para>
 453             自動的に永続ストレージが用いられるのがまずい場合もあるでしょう。
 454             そんな場合は、<classname>Zend_Auth</classname> クラスをバイパスして
 455             アダプタクラスを直接使用します。
 456             アダプタクラスを直接使用するとは、アダプタオブジェクトの設定と準備を行い、
 457             その <methodname>authenticate()</methodname> メソッドをコールするということです。
 458             アダプタ固有の詳細情報については、各アダプタのドキュメントで説明します。
 459             以下の例は、<classname>MyAuthAdapter</classname> を直接使用するものです。
 460         </para>
 461
 462         <programlisting language="php"><![CDATA[
 463 // 認証アダプタを設定します
 464 $authAdapter = new MyAuthAdapter($username, $password);
 465
 466 // 認証を試み、その結果を取得します
 467 $result = $authAdapter->authenticate();
 468
 469 if (!$result->isValid()) {
 470     // 認証に失敗したので、原因を表示します
 471     foreach ($result->getMessages() as $message) {
 472         echo "$message\n";
 473     }
 474 } else {
 475     // 認証に成功しました
 476     // $result->getIdentity() === $username
 477 }
 478 ]]></programlisting>
 479
 480     </sect2>
 481
 482 </sect1>
 483 <!--
 484 vim:se ts=4 sw=4 et:
 485 -->