repo_zf1/documentation/manual/en/module_specs/Zend_Auth_Adapter_OpenId.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.auth.adapter.openid">

    <title>Open ID Authentication</title>

    <sect2 id="zend.auth.adapter.openid.introduction">

        <title>Introduction</title>
        <para>
            The <classname>Zend_Auth_Adapter_OpenId</classname> adapter can be used to authenticate users using
            remote OpenID servers. This authentication method assumes that the user
            submits only their OpenID identity to the web application. They are
            then redirected to their OpenID provider to prove identity ownership
            using a password or some other method. This password is never provided to
            the web application.
        </para>
        <para>
            The OpenID identity is just a URI that points to a web site
            with information about a user, along with special tags that
            describes which server to use and which identity to submit there.
            You can read more about OpenID at the
            <ulink url="http://www.openid.net/">OpenID official site</ulink>.
        </para>
        <para>
            The <classname>Zend_Auth_Adapter_OpenId</classname> class wraps
            the <classname>Zend_OpenId_Consumer</classname> component, which implements the
            OpenID authentication protocol itself.
        </para>

        <note>
            <para>
                <classname>Zend_OpenId</classname> takes advantage of the <ulink url="http://php.net/gmp">GMP extension</ulink>,
                where available. Consider enabling the GMP extension for better performance when using
                <classname>Zend_Auth_Adapter_OpenId</classname>.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.auth.adapter.openid.specifics">
        <title>Specifics</title>
        <para>
            As is the case for all <classname>Zend_Auth</classname> adapters, the <classname>Zend_Auth_Adapter_OpenId</classname>
            class implements <classname>Zend_Auth_Adapter_Interface</classname>, which
            defines one method: <code>authenticate()</code>. This method performs
            the authentication itself, but the object must be prepared prior to
            calling it. Such adapter preparation includes setting up the OpenID
            identity and some other <classname>Zend_OpenId</classname> specific options.
        </para>

        <para>
            However, as opposed to other <classname>Zend_Auth</classname> adapters, <classname>Zend_Auth_Adapter_OpenId</classname>
            performs authentication on an external server in two
            separate HTTP requests. So the <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname> method
            must be called twice. On the first invocation the method won't return, but will
            redirect the user to their OpenID server. Then after the user is authenticated on the remote
            server, they will be redirected back and the script for this second
            request must call <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname>
            again to verify the signature which comes with the redirected request from the
            server to complete the authentication process. On this second invocation, the
            method will return the <classname>Zend_Auth_Result</classname> object as expected.
        </para>

        <para>
            The following example shows the usage of <classname>Zend_Auth_Adapter_OpenId</classname>.
            As previously mentioned, the <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname>
            must be called two times. The first time is after the user submits the HTML form with the
            <code>$_POST['openid_action']</code> set to <code>"login"</code>,
            and the second time is after the HTTP redirection from OpenID server with
            <code>$_GET['openid_mode']</code> or <code>$_POST['openid_mode']</code>
            set.
        </para>

        <programlisting role="php"><![CDATA[
<?php
$status = "";
$auth = Zend_Auth::getInstance();
if ((isset($_POST['openid_action']) &&
     $_POST['openid_action'] == "login" &&
     !empty($_POST['openid_identifier'])) ||
    isset($_GET['openid_mode']) ||
    isset($_POST['openid_mode'])) {
    $result = $auth->authenticate(
        new Zend_Auth_Adapter_OpenId(@$_POST['openid_identifier']));
    if ($result->isValid()) {
        $status = "You are logged in as "
                . $auth->getIdentity()
                . "<br>\n";
    } else {
        $auth->clearIdentity();
        foreach ($result->getMessages() as $message) {
            $status .= "$message<br>\n";
        }
    }
} else if ($auth->hasIdentity()) {
    if (isset($_POST['openid_action']) &&
        $_POST['openid_action'] == "logout") {
        $auth->clearIdentity();
    } else {
        $status = "You are logged in as "
                . $auth->getIdentity()
                . "<br>\n";
    }
}
?>
<html><body>
<?php echo htmlspecialchars($status);?>
<form method="post"><fieldset>
<legend>OpenID Login</legend>
<input type="text" name="openid_identifier" value="">
<input type="submit" name="openid_action" value="login">
<input type="submit" name="openid_action" value="logout">
</fieldset></form></body></html>
*/
]]></programlisting>

        <para>
            You may customize the OpenID authentication process in several way.
            You can, for example, receive the redirect from the OpenID server on a separate page,
            specifying the "root" of web site and using a custom
            <classname>Zend_OpenId_Consumer_Storage</classname> or a custom
            <classname>Zend_Controller_Response</classname>. You may also use
            the Simple Registration Extension to retrieve information about
            user from the OpenID server. All of these possibilities are described
            in more detail in the <classname>Zend_OpenId_Consumer</classname>
            chapter.
        </para>

    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->