documentation/manual/pl/module_specs/Zend_Auth.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.auth.introduction">
   4
   5     <title>Wprowadzenie</title>
   6
   7     <para>
   8         <classname>Zend_Auth</classname> zapewnia <acronym>API</acronym> do
   9         uwierzytelniania oraz zawiera konkretne adaptery uwierzytelniania dla
  10         najczęstszych przypadków użycia.
  11     </para>
  12
  13     <para>
  14         Komponent <classname>Zend_Auth</classname> jest związany tylko z
  15         <emphasis>uwierzytelnianiem</emphasis>, a nie z
  16         <emphasis>autoryzacją</emphasis>.
  17         Uwierzytelnianie luźno definiujemy jako określanie w oparciu o pewien
  18         zestaw danych tego, czy dana jednostka jest tym na co wygląda (np.
  19         identyfikacja). Autoryzacja, proces decydowania o tym, czy zezwolić
  20         danej jednostce na dostęp lub przeprowadzanie operacji na innych
  21         jednostkach, jest poza polem działania <classname>Zend_Auth</classname>.
  22         Aby uzyskać więcej informacji o autoryzacji i kontroli dostępu za pomocą
  23         Zend Framework, proszę zobacz <link linkend="zend.acl"><classname>Zend_Acl</classname></link>.
  24     </para>
  25
  26     <note>
  27         <para>
  28             Klasa <classname>Zend_Auth</classname> implementuje wzorzec singletona, czyli
  29             dostępna jest tylko jej jedna instancja - za pomocą statycznej
  30             metody <methodname>getInstance()</methodname>. Oznacza to, że użycie operatorów
  31             <emphasis>new</emphasis> oraz <emphasis>clone</emphasis> nie będzie możliwe z klasą
  32             <classname>Zend_Auth</classname>; zamiast nich użyj metody
  33             <methodname>Zend_Auth::getInstance()</methodname>.
  34         </para>
  35     </note>
  36
  37     <sect2 id="zend.auth.introduction.adapters">
  38
  39         <title>Adaptery</title>
  40
  41         <para>
  42             Adapter <classname>Zend_Auth</classname> jest używany do uwierzytelniania
  43             na podstawie serwisu konkretnego typu, takiego jak <acronym>LDAP</acronym>,
  44             <acronym>RDBMS</acronym>, lub system plików. Różne adaptery mogą
  45             mieć różne opcje i mogą inaczej się zachowywać,
  46             ale niektóre podstawowe funkcjonalności są wspólne dla wszystkich
  47             adapterów. Na przykład akceptowanie danych uwierzytelniania,
  48             przeprowadzanie zapytań do serwisu uwierzytelniania i zwracanie
  49             rezultatów są wspólne dla adapterów <classname>Zend_Auth</classname>.
  50         </para>
  51
  52         <para>
  53             Każda klasa adaptera <classname>Zend_Auth</classname> implementuje interfejs
  54             <classname>Zend_Auth_Adapter_Interface</classname>. Ten interfejs definiuje
  55             jedną metodę, <methodname>authenticate()</methodname>, którą klasa adaptera
  56             musi implementować dla zastosowań przeprowadzania zapytania
  57             uwierzytelniania. Każda klasa adaptera musi być przygotowana przed
  58             wywołaniem metody <methodname>authenticate()</methodname>. Przygotowanie takiego
  59             adaptera obejmuje ustawienie danych uwierzytelniania (np. nazwy
  60             użytkownika i hasła) oraz zdefiniowanie wartości dla specyficznych
  61             opcji adaptera, na przykład ustawienie połączenia do bazy danych dla
  62             adaptera tabeli bazy danych.
  63         </para>
  64
  65         <para>
  66             Poniżej jest przykładowy adapter uwierzytelniania, który do
  67             przeprowadzenia procesu wymaga ustawionej nazwy użytkownika oraz
  68             hasła. Inne szczegóły, takie jak sposób przeprowadzania zapytania
  69             uwierzytelniającego, zostały pominięte w celu zwiększenia
  70             czytelności:
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 class MyAuthAdapter implements Zend_Auth_Adapter_Interface
  75 {
  76     /**
  77      * Ustawia nazwę użytkownika oraz hasła dla uwierzytelniania
  78      *
  79      * @return void
  80      */
  81     public function __construct($username, $password)
  82     {
  83         // ...
  84     }
  85
  86     /**
  87      * Przeprowadza próbę uwierzytelniania
  88      *
  89      * @throws Zend_Auth_Adapter_Exception Jeśli uwierzytelnianie
  90      *                                     nie może być przeprowadzone
  91      * @return Zend_Auth_Result
  92      */
  93     public function authenticate()
  94     {
  95         // ...
  96     }
  97 }
  98 ]]></programlisting>
  99
 100         <para>
 101             Jak pokazano w bloku dokumentacyjnym, metoda <methodname>authenticate()</methodname>
 102             musi zwracać instancję <classname>Zend_Auth_Result</classname> (lub instancję klasy
 103             rozszerzającej <classname>Zend_Auth_Result</classname>). Jeśli z jakiegoś
 104             powodu przeprowadzenie zapytania uwierzytelniającego jest niemożliwe,
 105             metoda <methodname>authenticate()</methodname> powinna wyrzucić wyjątek
 106             rozszerzający <classname>Zend_Auth_Adapter_Exception</classname>.
 107         </para>
 108
 109     </sect2>
 110
 111     <sect2 id="zend.auth.introduction.results">
 112
 113         <title>Resultat</title>
 114
 115         <para>
 116             Adaptery <classname>Zend_Auth</classname> zwracają instancję
 117             <classname>Zend_Auth_Result</classname> za pomocą metody
 118             <methodname>authenticate()</methodname> w celu przekazania
 119             rezultatu próby uwierzytelniania. Adaptery wypełniają obiekt
 120             <classname>Zend_Auth_Result</classname> podczas konstrukcji,
 121             dlatego poniższe cztery metody zapewniają podstawowy zestaw
 122             operacji, które są wspólne dla rezultatów adapterów
 123             <classname>Zend_Auth</classname>:
 124         </para>
 125
 126         <itemizedlist>
 127             <listitem>
 128                 <para>
 129                     <methodname>isValid()</methodname> - zwraca logiczną wartość true
 130                     tylko wtedy, gdy rezultat reprezentuje udaną próbę
 131                     uwierzytelniania.
 132                 </para>
 133             </listitem>
 134             <listitem>
 135                 <para>
 136                     <methodname>getCode()</methodname> - zwraca identyfikator w postaci
 137                     stałej klasy <classname>Zend_Auth_Result</classname> dla
 138                     określenia powodu nieudanego uwierzytelniania lub
 139                     sprawdzenia czy uwierzytelnianie się udało. Metoda może
 140                     być użyta w sytuacjach gdy programista chce rozróżnić
 141                     poszczególne typy wyników uwierzytelniania. Pozwala to
 142                     na przykład programiście na zarządzanie szczegółowymi
 143                     statystykami na temat wyników uwierzytelniania. Innym
 144                     przykładem użycia tej funkcjonalności może być potrzeba
 145                     zapewnienia wiadomości informujących użytkownika o
 146                     przebiegu uwierzytelniania, ale jednak zalecane jest
 147                     rozważenie ryzyka jakie zachodzi przy przekazywaniu
 148                     użytkownikowi takich szczegółowych informacji, zamiast
 149                     podstawowej informacji o błędzie. Aby uzyskać więcej
 150                     informacji, zobacz poniżej.
 151                 </para>
 152             </listitem>
 153             <listitem>
 154                 <para>
 155                     <methodname>getIdentity()</methodname> - zwraca tożsamość próby
 156                     uwierzytelniania
 157                 </para>
 158             </listitem>
 159             <listitem>
 160                 <para>
 161                     <methodname>getMessages()</methodname> - zwraca tablicę wiadomości
 162                     odnoszących się do nieudanej próby uwierzytelniania
 163                 </para>
 164             </listitem>
 165         </itemizedlist>
 166
 167         <para>
 168             Programista może chcieć przeprowadzić jakieś specyficzne akcje
 169             zależne od typu wyniku uwierzytelniania. Przykładami operacji,
 170             które programiści mogą uznać za użyteczne, mogą być: blokowanie
 171             kont po zbyt dużej ilości nieudanych próbach logowania, zapiywanie
 172             adresów IP po wpisaniu przez użytkownika nieistnięjącej nazwy
 173             tożsamości czy zapewnienie własnych zdefiniowanych komunikatów po
 174             próbie uwierzytelniania. Dostępne są takie kody wyników:
 175         </para>
 176
 177         <programlisting language="php"><![CDATA[
 178 Zend_Auth_Result::SUCCESS
 179 Zend_Auth_Result::FAILURE
 180 Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
 181 Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
 182 Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
 183 Zend_Auth_Result::FAILURE_UNCATEGORIZED
 184 ]]></programlisting>
 185
 186         <para>
 187             Poniższy przykład pokazuje w jaki sposób programista może obsłużyć
 188             to kodzie:
 189         </para>
 190
 191         <programlisting language="php"><![CDATA[
 192 // wewnątrz akcji loginAction kontrolera AuthController
 193 $result = $this->_auth->authenticate($adapter);
 194
 195 switch ($result->getCode()) {
 196
 197     case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
 198         /** obsługujemy nieistniejącą tożsamość **/
 199         break;
 200
 201     case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
 202         /** obsługujemy nieprawidłowe hasło **/
 203         break;
 204
 205     case Zend_Auth_Result::SUCCESS:
 206         /** obsługujemy udane uwierzytelnianie **/
 207         break;
 208
 209     default:
 210         /** obsługujemy inne błędy **/
 211         break;
 212 }
 213 ]]></programlisting>
 214
 215     </sect2>
 216
 217     <sect2 id="zend.auth.introduction.persistence">
 218
 219         <title>Trwałość uwierzytelnionej tożsamości</title>
 220
 221         <para>
 222             Uwierzytelnianie żądania, które zawiera dane uwierzytelniające jest
 223             samo w sobie użyteczne, ale ważna jest także obsługa
 224             uwierzytelnionej tożsamości bez konieczności dołączania danych
 225             uwierzytelniających do każdego żądania.
 226         </para>
 227
 228         <para>
 229             <acronym>HTTP</acronym> jest protokołem niezachowującym stanu pomiędzy
 230             żądaniami, a techniki takie jak pliki cookie oraz sesje zostały
 231             stworzone w celu ułatwienia zarządzania stanem pomiędzy żądaniami w
 232             aplikacjach serwerowych.
 233         </para>
 234
 235         <sect3 id="zend.auth.introduction.persistence.default">
 236
 237             <title>Domyślne przechowywanie w sesji PHP</title>
 238
 239             <para>
 240                  Domyślnie <classname>Zend_Auth</classname> zapewnia trwały pojemnik do
 241                  przechowywania tożsamości pochodzącej z udanej próby
 242                  uwierzytelniania używając sesji <acronym>PHP</acronym>. Po udanej próbie
 243                  uwierzytelniania, metoda <methodname>Zend_Auth::authenticate()</methodname>
 244                  przechowuje wtrwałym pojemniku tożsamość pochodzącą z wyniku
 245                  uwierzytelniania. Jeśli nie skonfigurujemy tego inaczej, klasa
 246                  <classname>Zend_Auth</classname> użyje klasy pojemnika o nazwie
 247                  <classname>Zend_Auth_Storage_Session</classname>, który używa klasy
 248                  <link linkend="zend.session"><classname>Zend_Session</classname></link>.
 249                  Zamiast tego za pomocą metody <methodname>Zend_Auth::setStorage()</methodname>
 250                  może być ustawiona własna klasa implementująca interfejs
 251                  <classname>Zend_Auth_Storage_Interface</classname>.
 252
 253             </para>
 254
 255             <note>
 256                 <para>
 257                     Jeśli automatyczne przechowywanie tożsamości w trwałym
 258                     pojemniku nie jest odpowiednie dla konkretnego przypadku
 259                     użycia, to programiści mogą obyć się bez klasy
 260                     <classname>Zend_Auth</classname>, a zamiast niej użyć
 261                     bezpośrednio klasy adaptera.
 262                 </para>
 263             </note>
 264
 265             <example id="zend.auth.introduction.persistence.default.example">
 266
 267                 <title>Modyfikowanie przestrzeni nazw sesji</title>
 268
 269                 <para>
 270                     <classname>Zend_Auth_Storage_Session</classname> używa przestrzeni
 271                     nazw sesji o nazwie '<classname>Zend_Auth</classname>'. Ta przestrzeń
 272                     nazw może być nadpisana przez przekazanie innej wartości do
 273                     konstruktora klasy <classname>Zend_Auth_Storage_Session</classname>, a
 274                     ta wartość wewnętrznie jest przekazywana do konstruktora
 275                     klasy <classname>Zend_Session_Namespace</classname>. Powinno to
 276                     nastąpić zanim przeprowadzone zostanie uwierzytelnianie,
 277                     ponieważ metoda <methodname>Zend_Auth::authenticate()</methodname>
 278                     automatycznie zapisuje dane tożsamości.
 279                 </para>
 280
 281                 <programlisting language="php"><![CDATA[
 282 // Zapisujemy referencję do pojedynczej instancji Zend_Auth
 283 $auth = Zend_Auth::getInstance();
 284
 285 // Używamy przestrzeni nazw 'someNamespace' zamiast 'Zend_Auth'
 286 $auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));
 287
 288 /**
 289  * @todo Ustawić adapter uwierzytelniania, $authAdapter
 290  */
 291
 292 // Uwierzytelniamy, zapisując wynik i przechowując tożsamość
 293 // po udanym uwierzytelnieniu
 294 $result = $auth->authenticate($authAdapter);
 295 ]]></programlisting>
 296
 297             </example>
 298
 299         </sect3>
 300
 301         <sect3 id="zend.auth.introduction.persistence.custom">
 302
 303             <title>Implementacja własnego pojemnika</title>
 304
 305             <para>
 306                 Czasem programiści mogą potrzebować użyć innego sposobu
 307                 trwałego przechowywania tożsamości niż ten zapewniony przez
 308                 <classname>Zend_Auth_Storage_Session</classname>. W takich przypadkach
 309                 programiści mogą po prostu zaimplementować interfejs
 310                 <classname>Zend_Auth_Storage_Interface</classname> i przekazać instancję
 311                 klasy do metody <methodname>Zend_Auth::setStorage()</methodname>.
 312             </para>
 313
 314             <example id="zend.auth.introduction.persistence.custom.example">
 315
 316                 <title>Użycie własnej klasy do przechowywania tożsamości</title>
 317
 318                 <para>
 319                     W celu użycia klasy trwale przechowującej tożsamość innej
 320                     niż <classname>Zend_Auth_Storage_Session</classname>, programista
 321                     implementuje interfejs
 322                     <classname>Zend_Auth_Storage_Interface</classname>:
 323                 </para>
 324
 325                 <programlisting language="php"><![CDATA[
 326 class MyStorage implements Zend_Auth_Storage_Interface
 327 {
 328     /**
 329      * Zwraca wartość logiczną true tylko wtedy gdy pojemnik jest pusty
 330      *
 331      * @throws Zend_Auth_Storage_Exception Jeśli okreslenie czy pojemnik
 332      *                                     jest pusty jest niemożliwe
 333      * @return boolean
 334      */
 335     public function isEmpty()
 336     {
 337         /**
 338          * @todo implementacja
 339          */
 340     }
 341
 342     /**
 343      * Zwraca zawartość pojemnika
 344      *
 345      * Zachowanie jest nieokreślone w przypadku gdy pojemnik jest pusty.
 346      *
 347      * @throws Zend_Auth_Storage_Exception Jeśli odczyt zawartości
 348      *                                     pojemnika jest niemożliwy
 349      * @return mixed
 350      */
 351     public function read()
 352     {
 353         /**
 354          * @todo implementacja
 355          */
 356     }
 357
 358     /**
 359      * Zapisuje zawartość $contents w pojemniku
 360      *
 361      * @param  mixed $contents
 362      * @throws Zend_Auth_Storage_Exception Jeśli zapisanie zawartości $contents
 363      *                                     do pojemnika jest niemożliwe
 364      * @return void
 365      */
 366     public function write($contents)
 367     {
 368         /**
 369          * @todo implementacja
 370          */
 371     }
 372
 373     /**
 374      * Czyści zawartość pojemnika
 375      *
 376      * @throws Zend_Auth_Storage_Exception Jeśli wyczyszczenie zawartości
 377      *                                     pojemnika jest niemożliwe
 378      * @return void
 379      */
 380     public function clear()
 381     {
 382         /**
 383          * @todo implementacja
 384          */
 385     }
 386
 387 }
 388 ]]></programlisting>
 389
 390                 <para>
 391                     W celu użycia własnej klasy pojemnika, wywołaj metodę
 392                     <methodname>Zend_Auth::setStorage()</methodname> przed przeprowadzeniem
 393                     zapytania uwierzytelniającego:
 394                 </para>
 395
 396                 <programlisting language="php"><![CDATA[<?php
 397 // Instruujemy klasę Zend_Auth aby użyła niestandardowej klasy pojemnika
 398 Zend_Auth::getInstance()->setStorage(new MyStorage());
 399
 400 /**
 401  * @todo Ustawić adapter uwierzytelniania, $authAdapter
 402  */
 403
 404 // Uwierzytelniamy, zapisując wynik i przechowując tożsamość po udanym uwierzytelnieniu
 405 $result = Zend_Auth::getInstance()->authenticate($authAdapter);
 406 ]]></programlisting>
 407
 408             </example>
 409
 410         </sect3>
 411
 412     </sect2>
 413
 414     <sect2 id="zend.auth.introduction.using">
 415
 416         <title>Użycie</title>
 417
 418         <para>
 419             Są dwa możliwe sposoby użycia adapterów <classname>Zend_Auth</classname>:
 420         </para>
 421
 422         <orderedlist>
 423             <listitem>
 424                 <para>
 425                     pośrednio, za pomocą metody
 426                     <methodname>Zend_Auth::authenticate()</methodname>
 427                 </para>
 428             </listitem>
 429             <listitem>
 430                 <para>
 431                     bezpośrednio, za pomocą metody <methodname>authenticate()</methodname>
 432                     adaptera
 433                 </para>
 434             </listitem>
 435         </orderedlist>
 436
 437         <para>
 438             Poniższy przykład pokazuje jak użyć adaptera <classname>Zend_Auth</classname>
 439             pośrednio, poprzez użycie klasy <classname>Zend_Auth</classname>:
 440         </para>
 441
 442         <programlisting language="php"><![CDATA[
 443 // Pobieramy instancję Zend_Auth
 444 $auth = Zend_Auth::getInstance();
 445
 446 // Ustawiamy adapter uwierzytelniania
 447 $authAdapter = new MyAuthAdapter($username, $password);
 448
 449 // Przeprowadzamy uwierzytelnianie, zapisując rezultat
 450 $result = $auth->authenticate($authAdapter);
 451
 452 if (!$result->isValid()) {
 453     // Uwierzytelnianie nieudane; wyświetlamy powody
 454     foreach ($result->getMessages() as $message) {
 455         echo "$message\n";
 456     }
 457 } else {
 458     // Uwierzytelnianie udane; tożsamość ($username) jest zapisana w sesji
 459     // $result->getIdentity() === $auth->getIdentity()
 460     // $result->getIdentity() === $username
 461 }]]></programlisting>
 462
 463         <para>
 464             Jeśli uwierzytelnianie zostało przeprowadzone w żądaniu tak jak w
 465             powyższym przykładzie, prostą sprawą  jest sprawdzenie czy istnieje
 466             pomyślnie uwierzytelniona tożsamość:
 467         </para>
 468
 469         <programlisting language="php"><![CDATA[
 470 $auth = Zend_Auth::getInstance();
 471 if ($auth->hasIdentity()) {
 472     // Tożsamość istnieje; pobieramy ją
 473     $identity = $auth->getIdentity();
 474 }
 475 ]]></programlisting>
 476
 477         <para>
 478             Aby usunąć tożsamość z trwałego pojemnika, użyj po prostu metody
 479             <methodname>clearIdentity()</methodname>. Typowo może być to użyte do
 480             implementacji w aplikacji operacji wylogowania:
 481         </para>
 482
 483         <programlisting language="php"><![CDATA[
 484 Zend_Auth::getInstance()->clearIdentity();
 485 ]]></programlisting>
 486
 487         <para>
 488             Gdy automatyczne użycie trwałego pojemnika jest nieodpowiednie w
 489             konkretnym przypadku, programista może w prostu sposób ominąć
 490             użycie klasy <classname>Zend_Auth</classname>, używając bezpośrednio klasy
 491             adaptera. Bezpośrednie użycie klasy adaptera powoduje skonfigurowanie
 492             i przygotowanie obiektu adaptera, a następnie wywołanie metody
 493             <methodname>authenticate()</methodname>. Szczegóły specyficzne dla adaptera są
 494             opisane w dokumentacji dla każdego z adapterów. Poniższy przykład
 495             bezpośrednio używa <emphasis>MyAuthAdapter</emphasis>:
 496         </para>
 497
 498         <programlisting language="php"><![CDATA[
 499 // Ustawiamy adapter uwierzytelniania
 500 $authAdapter = new MyAuthAdapter($username, $password);
 501
 502 // Przeprowadzamy uwierzytelnianie, zapisując rezultat
 503 $result = $authAdapter->authenticate();
 504
 505 if (!$result->isValid()) {
 506     // Uwierzytelnianie nieudane; wyświetlamy powody
 507     foreach ($result->getMessages() as $message) {
 508         echo "$message\n";
 509     }
 510 } else {
 511     // Uwierzytelnianie udane
 512     // $result->getIdentity() === $username
 513 }
 514 ]]></programlisting>
 515
 516     </sect2>
 517
 518 </sect1>