documentation/manual/en/module_specs/Zend_Auth_Adapter_OpenId.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.auth.adapter.openid">
   4     <title>Open ID Authentication</title>
   5
   6     <sect2 id="zend.auth.adapter.openid.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The <classname>Zend_Auth_Adapter_OpenId</classname> adapter can be used to authenticate
  11             users using remote OpenID servers. This authentication method assumes that the user
  12             submits only their OpenID identity to the web application. They are
  13             then redirected to their OpenID provider to prove identity ownership
  14             using a password or some other method. This password is never provided to
  15             the web application.
  16         </para>
  17
  18         <para>
  19             The OpenID identity is just a <acronym>URI</acronym> that points to a web site
  20             with information about a user, along with special tags that
  21             describes which server to use and which identity to submit there.
  22             You can read more about OpenID at the
  23             <ulink url="http://www.openid.net/">OpenID official site</ulink>.
  24         </para>
  25
  26         <para>
  27             The <classname>Zend_Auth_Adapter_OpenId</classname> class wraps
  28             the <classname>Zend_OpenId_Consumer</classname> component, which implements the
  29             OpenID authentication protocol itself.
  30         </para>
  31
  32         <note>
  33             <para>
  34                 <classname>Zend_OpenId</classname> takes advantage of the <ulink
  35                     url="http://php.net/gmp">GMP extension</ulink>, where available. Consider
  36                 enabling the <acronym>GMP</acronym> extension for better performance when using
  37                 <classname>Zend_Auth_Adapter_OpenId</classname>.
  38             </para>
  39         </note>
  40     </sect2>
  41
  42     <sect2 id="zend.auth.adapter.openid.specifics">
  43         <title>Specifics</title>
  44
  45         <para>
  46             As is the case for all <classname>Zend_Auth</classname> adapters, the
  47             <classname>Zend_Auth_Adapter_OpenId</classname> class implements
  48             <classname>Zend_Auth_Adapter_Interface</classname>, which defines one method:
  49             <methodname>authenticate()</methodname>. This method performs the authentication itself,
  50             but the object must be prepared prior to calling it. Such adapter preparation includes
  51             setting up the OpenID identity and some other <classname>Zend_OpenId</classname>
  52             specific options.
  53         </para>
  54
  55         <para>
  56             However, as opposed to other <classname>Zend_Auth</classname> adapters,
  57             <classname>Zend_Auth_Adapter_OpenId</classname> performs authentication on an external
  58             server in two separate <acronym>HTTP</acronym> requests. So the
  59             <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> method must be called
  60             twice. On the first invocation the method won't return, but will redirect the user to
  61             their OpenID server. Then after the user is authenticated on the remote server, they
  62             will be redirected back and the script for this second request must call
  63             <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> again to verify the
  64             signature which comes with the redirected request from the server to complete the
  65             authentication process. On this second invocation, the method will return the
  66             <classname>Zend_Auth_Result</classname> object as expected.
  67         </para>
  68
  69         <para>
  70             The following example shows the usage of
  71             <classname>Zend_Auth_Adapter_OpenId</classname>. As previously mentioned, the
  72             <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> must be called two
  73             times. The first time is after the user submits the <acronym>HTML</acronym> form with
  74             the <varname>$_POST['openid_action']</varname> set to <emphasis>"login"</emphasis>,
  75             and the second time is after the <acronym>HTTP</acronym> redirection from OpenID server
  76             with <varname>$_GET['openid_mode']</varname> or
  77             <varname>$_POST['openid_mode']</varname> set.
  78         </para>
  79
  80         <programlisting language="php"><![CDATA[
  81 <?php
  82 $status = "";
  83 $auth = Zend_Auth::getInstance();
  84 if ((isset($_POST['openid_action']) &&
  85      $_POST['openid_action'] == "login" &&
  86      !empty($_POST['openid_identifier'])) ||
  87     isset($_GET['openid_mode']) ||
  88     isset($_POST['openid_mode'])) {
  89     $result = $auth->authenticate(
  90         new Zend_Auth_Adapter_OpenId(@$_POST['openid_identifier']));
  91     if ($result->isValid()) {
  92         $status = "You are logged in as "
  93                 . $auth->getIdentity()
  94                 . "<br>\n";
  95     } else {
  96         $auth->clearIdentity();
  97         foreach ($result->getMessages() as $message) {
  98             $status .= "$message<br>\n";
  99         }
 100     }
 101 } else if ($auth->hasIdentity()) {
 102     if (isset($_POST['openid_action']) &&
 103         $_POST['openid_action'] == "logout") {
 104         $auth->clearIdentity();
 105     } else {
 106         $status = "You are logged in as "
 107                 . $auth->getIdentity()
 108                 . "<br>\n";
 109     }
 110 }
 111 ?>
 112 <html><body>
 113 <?php echo htmlspecialchars($status);?>
 114 <form method="post"><fieldset>
 115 <legend>OpenID Login</legend>
 116 <input type="text" name="openid_identifier" value="">
 117 <input type="submit" name="openid_action" value="login">
 118 <input type="submit" name="openid_action" value="logout">
 119 </fieldset></form></body></html>
 120 */
 121 ]]></programlisting>
 122
 123         <para>
 124             You may customize the OpenID authentication process in several way.
 125             You can, for example, receive the redirect from the OpenID server on a separate page,
 126             specifying the "root" of web site and using a custom
 127             <classname>Zend_OpenId_Consumer_Storage</classname> or a custom
 128             <classname>Zend_Controller_Response</classname>. You may also use
 129             the Simple Registration Extension to retrieve information about
 130             user from the OpenID server. All of these possibilities are described
 131             in more detail in the <classname>Zend_OpenId_Consumer</classname>
 132             chapter.
 133         </para>
 134     </sect2>
 135 </sect1>
 136 <!--
 137 vim:se ts=4 sw=4 et:
 138 -->