/documentation/manual/de/module_specs/Zend_Auth.xml

https://github.com/decaoz/zf1 · XML · 492 lines · 423 code · 67 blank · 2 comment · 0 complexity · 0429af21ca28e75e734b4efbd1b12288 MD5 · raw file

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!-- EN-Revision: 24249 -->
  3. <!-- Reviewed: 20763 -->
  4. <sect1 id="zend.auth.introduction">
  5. <title>Einführung</title>
  6. <para>
  7. <classname>Zend_Auth</classname> bietet eine <acronym>API</acronym> für das Authentifizieren
  8. und enthält konkrete Authentifizierungs-Adapter für übliche Use-Case-Szenarien.
  9. </para>
  10. <para>
  11. <classname>Zend_Auth</classname> behandelt nur die
  12. <emphasis>Authentifizierung</emphasis> und nicht die
  13. <emphasis>Authorisierung</emphasis>. Authentifizierung ist frei definiert als
  14. das Ermitteln, ob eine Entität aktuell das ist, was sie vorgibt zu sein (z.B.
  15. Identifizierung), basierend auf einem Set von Anmeldedaten. Authorisierung, der Prozess des
  16. Entscheidens, ob es einer Entität erlaubt wird, auf andere Entitäten Zugriff zu erhalten,
  17. oder um auf diesen Operationen durchzuführen, ist ausserhalb der Möglichkeit von
  18. <classname>Zend_Auth</classname>. Für weitere Informationen über Authorisierung und
  19. Zugriffskontrolle mit dem Zend Framework, sollte <link
  20. linkend="zend.acl"><classname>Zend_Acl</classname></link> angeschaut werden.
  21. </para>
  22. <note>
  23. <para>
  24. Die <classname>Zend_Auth</classname> Klasse implementiert das Singleton Pattern - nur
  25. eine Instanz der Klasse ist vorhanden - durch ihre statische
  26. Methode <methodname>getInstance()</methodname>. Das bedeutet, dass die Verwendung des
  27. Operators <emphasis>new</emphasis> und des Schlüsselworts <emphasis>clone</emphasis> mit der
  28. Klasse <classname>Zend_Auth</classname> nicht funktioniert; stattdessen muß
  29. <methodname>Zend_Auth::getInstance()</methodname> verwendet werden.
  30. </para>
  31. </note>
  32. <sect2 id="zend.auth.introduction.adapters">
  33. <title>Adapter</title>
  34. <para>
  35. Ein <classname>Zend_Auth</classname>-Adapter wird verwendet, um sich gegenüber einem
  36. speziellen Typ von Authentifizierungsdiensten zu authentifizieren, wie
  37. <acronym>LDAP</acronym>, <acronym>RDBMS</acronym>, oder dateibasierenden Speichern.
  38. Verschiedene Adapter besitzen leicht unterschiedliche Optionen und Verhaltensweisen,
  39. aber einige grundlegende Dinge haben Authentifizierungsadapter gemeinsam. Zum Beispiel
  40. dass für die Authentifizierung Anmeldedaten akzeptiert werden (enthält auch vorgegebene
  41. Identitäten), dass Abfragen am Authentifizierungsservice durchgeführt werden, und dass
  42. Ergebnisse zurückgegeben werden, sind für <classname>Zend_Auth</classname>-Adapter
  43. gebräuchlich.
  44. </para>
  45. <para>
  46. Jede <classname>Zend_Auth</classname>-Adapterklasse implementiert
  47. <classname>Zend_Auth_Adapter_Interface</classname>. Dieses Interface definiert eine
  48. Methode <methodname>authenticate()</methodname>, die eine Adapterklasse
  49. implementieren muß, um eine Authentifizierungsanfrage auszuführen. Jede Adapterklasse
  50. muß vorher vorbereitet werden, bevor <methodname>authenticate()</methodname> aufgerufen
  51. wird. Diese Vorbereitung des Adapters enthält das Setzen der Anmeldedaten (z.B.
  52. Benutzername und Passwort) und die Definition von Werten für adapterspezifische
  53. Konfigurationoptionen, wie Datenbankverbindungsdaten für einen Datenbank-Tabellen-Adapter.
  54. </para>
  55. <para>
  56. Das folgende ist ein Beispiel eines Authentifierungs-Adapters der einen Benutzernamen
  57. und ein Passwort für die Authentifizierung benötigt. Andere Details, wie zum Beispiel
  58. der Authentifizierungs-Service abgefragt wird, werden der Kürze halber ausgelassen:
  59. </para>
  60. <programlisting language="php"><![CDATA[
  61. class MyAuthAdapter implements Zend_Auth_Adapter_Interface
  62. {
  63. /**
  64. * Setzt Benutzername und Passwort für die Authentifizierung
  65. *
  66. * @return void
  67. */
  68. public function __construct($username, $password)
  69. {
  70. // ...
  71. }
  72. /**
  73. * Führt einen Authentifizierungs-Versuch durch
  74. *
  75. * @throws Zend_Auth_Adapter_Exception Wenn die Authentifizierung nicht
  76. * durchgeführt wurde
  77. * @return Zend_Auth_Result
  78. */
  79. public function authenticate()
  80. {
  81. // ...
  82. }
  83. }
  84. ]]></programlisting>
  85. <para>
  86. Wie im Docblock angegeben, muß <methodname>authenticate()</methodname> eine Instanz von
  87. <classname>Zend_Auth_Result</classname> (oder einer von
  88. <classname>Zend_Auth_Result</classname> abgeleiteten Klassen) zurückgeben. Wenn aus
  89. bestimmten Gründen eine Durchführung einer Authentifizierungsanfrage nicht möglich
  90. ist, sollte <methodname>authenticate()</methodname> eine Ausnahme werfen, die von
  91. <classname>Zend_Auth_Adapter_Exception</classname> abgeleitet ist.
  92. </para>
  93. </sect2>
  94. <sect2 id="zend.auth.introduction.results">
  95. <title>Ergebnisse</title>
  96. <para>
  97. <classname>Zend_Auth</classname>-Adapter geben eine Instanz von
  98. <classname>Zend_Auth_Result</classname> mit Hilfe von
  99. <methodname>authenticate()</methodname> zurück, um die Ergebnisse des
  100. Authentifizierungsversuchs darzustellen. Adapter befüllen das
  101. Objekt <classname>Zend_Auth_Result</classname> bei der Erstellung, so dass die folgenden
  102. vier Methoden ein grundsätzliches Set von benutzerbezogenen Operationen bieten, die für
  103. die Ergebnisse von <classname>Zend_Auth</classname> Adapter üblich sind:
  104. </para>
  105. <itemizedlist>
  106. <listitem>
  107. <para>
  108. <methodname>isValid()</methodname> - Gibt <constant>TRUE</constant> zurück, wenn
  109. und nur wenn das Ergebnis einen erfolgreichen Authentifizierungsversuch
  110. repräsentiert.
  111. </para>
  112. </listitem>
  113. <listitem>
  114. <para>
  115. <methodname>getCode()</methodname> - Gibt einen konstanten
  116. <classname>Zend_Auth_Result</classname>-Identifizierer zurück, damit der Typ des
  117. Authentifizierungsfehlers, oder des Erfolgs der stattgefunden hat,
  118. ermittelt werden kann. Das kann in Situationen verwendet werden, in denen der
  119. Entwickler die verschiedenen Ergebnistypen der Authentifizierung
  120. unterschiedlich behandeln will. Das erlaubt es dem Entwickler zum Beispiel
  121. detailierte Statistiken über die Authentifizierungsergebnisse zu erhalten.
  122. Eine andere Verwendung dieses Features ist es spezielle, benutzerdefinierte
  123. Nachrichten anzubieten, um Benutzern eine bessere Usability zu ermöglichen,
  124. einfach dadurch dass Entwickler dazu aufgerufen sind, die Risiken solche
  125. detaillierte Informationen Benutzern anzubieten, statt einer generellen
  126. Nachricht eines Authentifizierungsfehlers. Für weitere Informationen siehe
  127. die Notiz anbei.
  128. </para>
  129. </listitem>
  130. <listitem>
  131. <para>
  132. <methodname>getIdentity()</methodname> - Gibt die Identität des
  133. Authentifizierungsversuchs zurück
  134. </para>
  135. </listitem>
  136. <listitem>
  137. <para>
  138. <methodname>getMessages()</methodname> - Gibt ein Array von Nachrichten
  139. zurück nach einem fehlgeschlagenen Authentifizierungsversuch
  140. </para>
  141. </listitem>
  142. </itemizedlist>
  143. <para>
  144. Ein Entwickler möchte basierend auf dem Typ des Authentifizierungsergebnisses zu
  145. spezialisierteren Operationen verzweigen. Einige Operationen die für
  146. Entwickler nützlich sein können, sind zum Beispiel das Sperren von Konten nachdem zu oft
  147. ein falsches Passwort angegeben wurde, das Markieren von IP-Adressen, nachdem zuviele
  148. nicht existierende Identitäten angegeben wurden und das Anbieten von speziellen,
  149. benutzerdefinierten Nachrichten für Authentifizierungsergebnisse an den Benutzer. Die
  150. folgenden Ergebniscodes sind vorhanden:
  151. </para>
  152. <programlisting language="php"><![CDATA[
  153. Zend_Auth_Result::SUCCESS
  154. Zend_Auth_Result::FAILURE
  155. Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
  156. Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
  157. Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
  158. Zend_Auth_Result::FAILURE_UNCATEGORIZED
  159. ]]></programlisting>
  160. <para>
  161. Das folgende Beispiel zeigt, wie ein Entwickler anhand des Ergebniscodes verzweigen
  162. könnte:
  163. </para>
  164. <programlisting language="php"><![CDATA[
  165. // Innerhalb von AuthController / loginAction
  166. $result = $this->_auth->authenticate($adapter);
  167. switch ($result->getCode()) {
  168. case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
  169. /** Was wegen nicht existierender Identität machen **/
  170. break;
  171. case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
  172. /** Was wegen ungültigen Anmeldededaten machen **/
  173. break;
  174. case Zend_Auth_Result::SUCCESS:
  175. /** Was wegen erfolgreicher Authentifizierung machen **/
  176. break;
  177. default:
  178. /** Was wegen anderen Fehlern machen **/
  179. break;
  180. }
  181. ]]></programlisting>
  182. </sect2>
  183. <sect2 id="zend.auth.introduction.persistence">
  184. <title>Dauerhafte Identitäten</title>
  185. <para>
  186. Eine Anfrage zu authentifizieren, die Anmeldedaten enthält ist per se
  187. nützlich, aber auch wichtig, um die Authentifizierungs-Identität bearbeiten zu können,
  188. ohne dass immer die Anmeldedaten bei jeder Anfrage vorhanden sein müssen.
  189. </para>
  190. <para>
  191. Trotzdem ist <acronym>HTTP</acronym> ein statusloses Protokoll, und Techniken wie
  192. Cookies und Sessions wurden entwickelt um Stati über mehrere Anfragen hinweg in
  193. server-seitigen Web-Anwendungen zu erhalten.
  194. </para>
  195. <sect3 id="zend.auth.introduction.persistence.default">
  196. <title>Normale Persistenz in PHP-Sessions</title>
  197. <para>
  198. Standardmäßig bietet <classname>Zend_Auth</classname> dauerhafte Speicherung der
  199. Identität eines erfolgreichen Authentifizierungsversuches durch Verwendung der
  200. <acronym>PHP</acronym>-Session. Bei einem erfolgreichen Authentifizierungsversuch
  201. speichert <methodname>Zend_Auth::authenticate()</methodname> die Identität des
  202. Authentifizierungsergebnisses im persistenten Speicher. Solange die Konfiguration
  203. nicht verändert wird, verwendet <classname>Zend_Auth</classname> eine
  204. Speicherklasse die <classname>Zend_Auth_Storage_Session</classname> heißt und die
  205. im Gegenzug <link linkend="zend.session"><classname>Zend_Session</classname></link>
  206. verwendet. Eine eigene Klasse kann stattdessen verwendet werden, indem ein Objekt
  207. an <methodname>Zend_Auth::setStorage()</methodname> übergeben wird, welches
  208. <classname>Zend_Auth_Storage_Interface</classname> implementiert.
  209. </para>
  210. <note>
  211. <para>
  212. Wenn das automatische persistente Speichern der Identität für einen bestimmten
  213. Anwendungsfall nicht anwendbar ist, können Entwickler trotzdem die
  214. <classname>Zend_Auth</classname> Klasse weiterhin verwenden, statt direkt eine
  215. Adapterklasse anzusprechen.
  216. </para>
  217. </note>
  218. <example id="zend.auth.introduction.persistence.default.example">
  219. <title>Den Namensraum der Session ändern</title>
  220. <para>
  221. <classname>Zend_Auth_Storage_Session</classname> verwendet einen Session
  222. Namensraum von '<classname>Zend_Auth</classname>'. Dieser Namensraum kann
  223. überschrieben werden, indem ein anderer Wert an den Konstruktor von
  224. <classname>Zend_Auth_Storage_Session</classname> übergeben wird, und dieser Wert
  225. wird intern an den Konstruktor von <classname>Zend_Session_Namespace</classname>
  226. weitergereicht. Das sollte vor einem Versuch einer Authentifizierung stattfinden,
  227. da <methodname>Zend_Auth::authenticate()</methodname> die automatische
  228. Speicherung der Identität durchführt.
  229. </para>
  230. <programlisting language="php"><![CDATA[
  231. // Eine Referenz zur Singleton Instanz von Zend_Auth speichern
  232. $auth = Zend_Auth::getInstance();
  233. // 'someNamespace' statt 'Zend_Auth' verwenden
  234. $auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));
  235. /**
  236. * @todo Den Auth Adapter $authAdapter erstellen
  237. */
  238. // Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
  239. // persistent machen
  240. $result = $auth->authenticate($authAdapter);
  241. ]]></programlisting>
  242. </example>
  243. </sect3>
  244. <sect3 id="zend.auth.introduction.persistence.custom">
  245. <title>Eigene Speicher implementieren</title>
  246. <para>
  247. Zeitweise wollen Entwickler einen anderen Speichermechanismus für Identitäten
  248. verwenden als es von <classname>Zend_Auth_Storage_Session</classname> angeboten
  249. wird. Für solche Fälle können Entwickler einfach
  250. <classname>Zend_Auth_Storage_Interface</classname> implementieren und eine Instanz
  251. der Klasse an <methodname>Zend_Auth::setStorage()</methodname> übergeben.
  252. </para>
  253. <example id="zend.auth.introduction.persistence.custom.example">
  254. <title>Eine eigene Speicherklasse verwenden</title>
  255. <para>
  256. Um eine andere Speicherklasse für die Persistenz von Identitäten zu verwenden
  257. als sie durch <classname>Zend_Auth_Storage_Session</classname> angeboten wird,
  258. können Entwickler <classname>Zend_Auth_Storage_Interface</classname>
  259. implementieren:
  260. </para>
  261. <programlisting language="php"><![CDATA[
  262. class MyStorage implements Zend_Auth_Storage_Interface
  263. {
  264. /**
  265. * Gibt true zurück wenn und nur wenn der Speicher leer ist
  266. *
  267. * @throws Zend_Auth_Storage_Exception Wenn es unmöglich ist festzustellen,
  268. * ob der Speicher leer ist
  269. * @return boolean
  270. */
  271. public function isEmpty()
  272. {
  273. /**
  274. * @todo Implementierung
  275. */
  276. }
  277. /**
  278. * Gibt den Inhalt des Speichers zurück
  279. *
  280. * Das Verhalten ist undefiniert, wenn der Speicher leer ist.
  281. *
  282. * @throws Zend_Auth_Storage_Exception Wenn das Lesen vom Speicher
  283. * unmöglich ist
  284. * @return mixed
  285. */
  286. public function read()
  287. {
  288. /**
  289. * @todo Implementierung
  290. */
  291. }
  292. /**
  293. * Schreibt $contents in den Speicher
  294. *
  295. * @param mixed $contents
  296. * @throws Zend_Auth_Storage_Exception Wenn das Schreiben von $contents in
  297. * den Speicher unmöglich ist
  298. * @return void
  299. */
  300. public function write($contents)
  301. {
  302. /**
  303. * @todo Implementierung
  304. */
  305. }
  306. /**
  307. * Löscht die Intalte vom Speicher
  308. *
  309. * @throws Zend_Auth_Storage_Exception Wenn das Löschen der Inhalte vom
  310. * Speicher unmöglich ist
  311. * @return void
  312. */
  313. public function clear()
  314. {
  315. /**
  316. * @todo Implementierung
  317. */
  318. }
  319. }
  320. ]]></programlisting>
  321. <para>
  322. Um diese selbstgeschriebene Speicherklasse zu verwenden wird,
  323. <methodname>Zend_Auth::setStorage()</methodname> aufgerufen, bevor eine
  324. Authentifizierungsanfrage stattfindet:
  325. </para>
  326. <programlisting language="php"><![CDATA[
  327. // Zend_Auth anweisen, dass die selbstdefinierte Speicherklasse verwendet wird
  328. Zend_Auth::getInstance()->setStorage(new MyStorage());
  329. /**
  330. * @todo Den Auth Adapter $authAdapter erstellen
  331. */
  332. // Authentifizieren, das Ergebnis speichern, und die Identität bei Erfolg
  333. $result = Zend_Auth::getInstance()->authenticate($authAdapter);
  334. ]]></programlisting>
  335. </example>
  336. </sect3>
  337. </sect2>
  338. <sect2 id="zend.auth.introduction.using">
  339. <title>Verwendung</title>
  340. <para>
  341. Es gibt zwei vorhandene Wege um <classname>Zend_Auth</classname>-Adapter zu verwenden:
  342. </para>
  343. <orderedlist>
  344. <listitem>
  345. <para>
  346. Indirekt durch <methodname>Zend_Auth::authenticate()</methodname>
  347. </para>
  348. </listitem>
  349. <listitem>
  350. <para>
  351. Direkt durch die <methodname>authenticate()</methodname> Methode des Adapters
  352. </para>
  353. </listitem>
  354. </orderedlist>
  355. <para>
  356. Das folgende Beispiel zeigt, wie ein <classname>Zend_Auth</classname>-Adapter indirekt
  357. verwendet werden kann, durch die Verwendung der Klasse <classname>Zend_Auth</classname>:
  358. </para>
  359. <programlisting language="php"><![CDATA[
  360. // Eine Referenz zur Singleton-Instanz von Zend_Auth erhalten
  361. $auth = Zend_Auth::getInstance();
  362. // Authentifizierungs Adapter erstellen
  363. $authAdapter = new MyAuthAdapter($username, $password);
  364. // Authentifizierungsversuch, das Ergebnis abspeichern
  365. $result = $auth->authenticate($authAdapter);
  366. if (!$result->isValid()) {
  367. // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
  368. foreach ($result->getMessages() as $message) {
  369. echo "$message\n";
  370. }
  371. } else {
  372. // Authentifizierung erfolgreich; die Identität ($username) wird in
  373. // der Session gespeichert
  374. // $result->getIdentity() === $auth->getIdentity()
  375. // $result->getIdentity() === $username
  376. }
  377. ]]></programlisting>
  378. <para>
  379. Sobald die Authentifizierung in einer Anfrage durchgeführt wurde, so wie im obigen
  380. Beispiel, ist es sehr einfach zu prüfen, ob eine erfolgreich authentifizierte Identität
  381. existiert:
  382. </para>
  383. <programlisting language="php"><![CDATA[
  384. $auth = Zend_Auth::getInstance();
  385. if ($auth->hasIdentity()) {
  386. // Identität existiert; auslesen
  387. $identity = $auth->getIdentity();
  388. }
  389. ]]></programlisting>
  390. <para>
  391. Um eine Identität vom persistenten Speicher zu entfernen, muß einfach die
  392. Methode <methodname>clearIdentity()</methodname> verwendet werden. Das würde
  393. typischerweise für die Implementierung einer "Abmelde"-Operation in einer
  394. Anwendung Verwendung finden.
  395. </para>
  396. <programlisting language="php"><![CDATA[
  397. Zend_Auth::getInstance()->clearIdentity();
  398. ]]></programlisting>
  399. <para>
  400. Wenn die automatische Verwendung von persistenten Speichern für einen bestimmten
  401. Verwendungszweck unangebracht ist, kann ein Entwickler einfach die Verwendung der
  402. Klasse <classname>Zend_Auth</classname> umgehen, und eine Adapterklasse direkt
  403. verwenden. Die direkte Verwendung einer Adapterklasse enthält das Konfigurieren und
  404. Vorbereiten eines Adapter-Objekts und den Aufruf dessen
  405. Methode <methodname>authenticate()</methodname>. Adapter-spezifische Details werden in
  406. der Dokumentation jedes Adapters besprochen. Das folgende Beispeil verwendet
  407. <classname>MyAuthAdapter</classname> direkt:
  408. </para>
  409. <programlisting language="php"><![CDATA[
  410. // Den Authentifizierungsadapter erstellen
  411. $authAdapter = new MyAuthAdapter($username, $password);
  412. // Authentifizierungsversuch, speichere das Ergebnis
  413. $result = $authAdapter->authenticate();
  414. if (!$result->isValid()) {
  415. // Authentifizierung fehlgeschlagen; die genauen Gründe ausgeben
  416. foreach ($result->getMessages() as $message) {
  417. echo "$message\n";
  418. }
  419. } else {
  420. // Authentifizierung erfolgreich
  421. // $result->getIdentity() === $username
  422. }
  423. ]]></programlisting>
  424. </sect2>
  425. </sect1>