documentation/manual/en/module_specs/Zend_Gdata_AuthSub.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.authsub">
   4     <title>Authenticating with AuthSub</title>
   5
   6     <para>
   7         The AuthSub mechanism enables you to write web applications
   8         that acquire authenticated access Google Data services,
   9         without having to write code that handles user credentials.
  10     </para>
  11
  12     <para>
  13         See <ulink
  14             url="http://code.google.com/apis/accounts/AuthForWebApps.html">http://code.google.com/apis/accounts/AuthForWebApps.html</ulink>
  15         for more information about Google Data AuthSub authentication.
  16     </para>
  17
  18     <para>
  19         The Google documentation says the ClientLogin mechanism is appropriate
  20         for "installed applications" whereas the AuthSub mechanism is
  21         for "web applications." The difference is that AuthSub requires
  22         interaction from the user, and a browser interface that can react
  23         to redirection requests. The ClientLogin solution uses <acronym>PHP</acronym> code to
  24         supply the account credentials; the user is not required to enter her
  25         credentials interactively.
  26     </para>
  27
  28     <para>
  29         The account credentials supplied via the AuthSub mechanism are
  30         entered by the user of the web application. Therefore they must be
  31         account credentials that are known to that user.
  32     </para>
  33
  34     <note>
  35         <title>Registered applications</title>
  36
  37         <para>
  38             <classname>Zend_Gdata</classname> currently does not support use of secure tokens,
  39             because the AuthSub authentication does not support passing a digital certificate
  40             to acquire a secure token.
  41         </para>
  42     </note>
  43
  44     <sect2 id="zend.gdata.authsub.login">
  45         <title>Creating an AuthSub authenticated Http Client</title>
  46
  47         <para>
  48             Your <acronym>PHP</acronym> application should provide a hyperlink to the
  49             Google <acronym>URL</acronym> that performs authentication. The static function
  50             <methodname>Zend_Gdata_AuthSub::getAuthSubTokenUri()</methodname>
  51             provides the correct <acronym>URL</acronym>. The arguments to this function include
  52             the <acronym>URL</acronym> to your <acronym>PHP</acronym> application so that Google can
  53             redirect the user's browser back to your application after the user's
  54             credentials have been verified.
  55         </para>
  56
  57         <para>
  58             After Google's authentication server redirects the user's browser
  59             back to the current application, a GET request parameter is set,
  60             called <emphasis>token</emphasis>.
  61             The value of this parameter is a single-use token that can be
  62             used for authenticated access.
  63             This token can be converted into a multi-use token and stored
  64             in your session.
  65         </para>
  66
  67         <para>
  68             Then use the token value in a call to
  69             <methodname>Zend_Gdata_AuthSub::getHttpClient()</methodname>.
  70             This function returns an instance of <classname>Zend_Http_Client</classname>,
  71             with appropriate headers set so that subsequent requests your
  72             application submits using that <acronym>HTTP</acronym> Client are also authenticated.
  73         </para>
  74
  75         <para>
  76             Below is an example of <acronym>PHP</acronym> code for a web application
  77             to acquire authentication to use the Google Calendar service
  78             and create a <classname>Zend_Gdata</classname> client object using that authenticated
  79             <acronym>HTTP</acronym> Client.
  80         </para>
  81
  82         <programlisting language="php"><![CDATA[
  83 $my_calendar = 'http://www.google.com/calendar/feeds/default/private/full';
  84
  85 if (!isset($_SESSION['cal_token'])) {
  86     if (isset($_GET['token'])) {
  87         // You can convert the single-use token to a session token.
  88         $session_token =
  89             Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
  90         // Store the session token in our session.
  91         $_SESSION['cal_token'] = $session_token;
  92     } else {
  93         // Display link to generate single-use token
  94         $googleUri = Zend_Gdata_AuthSub::getAuthSubTokenUri(
  95             'http://'. $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'],
  96             $my_calendar, 0, 1);
  97         echo "Click <a href='$googleUri'>here</a> " .
  98              "to authorize this application.";
  99         exit();
 100     }
 101 }
 102
 103 // Create an authenticated HTTP Client to talk to Google.
 104 $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['cal_token']);
 105
 106 // Create a Gdata object using the authenticated Http Client
 107 $cal = new Zend_Gdata_Calendar($client);
 108 ]]></programlisting>
 109     </sect2>
 110
 111     <sect2 id="zend.gdata.authsub.logout">
 112         <title>Revoking AuthSub authentication</title>
 113
 114         <para>
 115             To terminate the authenticated status of a given token, use the
 116             <methodname>Zend_Gdata_AuthSub::AuthSubRevokeToken()</methodname>
 117             static function. Otherwise, the token is still valid for
 118             some time.
 119         </para>
 120
 121         <programlisting language="php"><![CDATA[
 122 // Carefully construct this value to avoid application security problems.
 123 $php_self = htmlentities(substr($_SERVER['PHP_SELF'],
 124                          0,
 125                          strcspn($_SERVER['PHP_SELF'], "\n\r")),
 126                          ENT_QUOTES);
 127
 128 if (isset($_GET['logout'])) {
 129     Zend_Gdata_AuthSub::AuthSubRevokeToken($_SESSION['cal_token']);
 130     unset($_SESSION['cal_token']);
 131     header('Location: ' . $php_self);
 132     exit();
 133 }
 134 ]]></programlisting>
 135
 136         <note>
 137             <title>Security notes</title>
 138
 139             <para>
 140                 The treatment of the <varname>$php_self</varname> variable in the
 141                 example above is a general security guideline, it is not
 142                 specific to <classname>Zend_Gdata</classname>. You should always filter content you
 143                 output to <acronym>HTTP</acronym> headers.
 144             </para>
 145
 146             <para>
 147                 Regarding revoking authentication tokens, it is recommended to
 148                 do this when the user is finished with her Google Data session.
 149                 The possibility that someone can intercept the token and use
 150                 it for malicious purposes is very small, but nevertheless it is
 151                 a good practice to terminate authenticated access to any service.
 152             </para>
 153         </note>
 154     </sect2>
 155 </sect1>