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 <acronym>URI</acronym> 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 <acronym>GMP</acronym> 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:
            <methodname>authenticate()</methodname>. 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 <acronym>HTTP</acronym> requests. So the
            <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> 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
            <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> 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
            <methodname>Zend_Auth_Adapter_OpenId::authenticate()</methodname> must be called two
            times. The first time is after the user submits the <acronym>HTML</acronym> form with
            the <varname>$_POST['openid_action']</varname> set to <emphasis>"login"</emphasis>,
            and the second time is after the <acronym>HTTP</acronym> redirection from OpenID server
            with <varname>$_GET['openid_mode']</varname> or
            <varname>$_POST['openid_mode']</varname> set.
        </para>

        <programlisting language="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:
-->