documentation/manual/en/module_specs/Zend_Gdata_ClientLogin.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.clientlogin">
   4     <title>Authenticating with ClientLogin</title>
   5
   6     <para>
   7         The ClientLogin mechanism enables you to write <acronym>PHP</acronym> application
   8         that acquire authenticated access to Google Services,
   9         specifying a user's credentials in the <acronym>HTTP</acronym> Client.
  10     </para>
  11
  12     <para>
  13         See <ulink
  14             url="http://code.google.com/apis/accounts/AuthForInstalledApps.html">http://code.google.com/apis/accounts/AuthForInstalledApps.html</ulink>
  15         for more information about Google Data ClientLogin 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 ClientLogin mechanism must
  30         be valid credentials for Google services, but they are not required
  31         to be those of the user who is using the <acronym>PHP</acronym> application.
  32     </para>
  33
  34     <sect2 id="zend.gdata.clientlogin.login">
  35         <title>Creating a ClientLogin authenticated Http Client</title>
  36
  37         <para>
  38             The process of creating an authenticated <acronym>HTTP</acronym> client using
  39             the ClientLogin mechanism is to call the static function
  40             <methodname>Zend_Gdata_ClientLogin::getHttpClient()</methodname>
  41             and pass the Google account credentials in plain text.
  42             The return value of this function is an object of class
  43             <classname>Zend_Http_Client</classname>.
  44         </para>
  45
  46         <para>
  47             The optional third parameter is the name of the Google Data
  48             service. For instance, this can be 'cl' for Google Calendar.
  49             The default is "xapi", which is recognized by Google Data
  50             servers as a generic service name.
  51         </para>
  52
  53         <para>
  54             The optional fourth parameter is an instance of <classname>Zend_Http_Client</classname>.
  55             This allows you to set options in the client, such as proxy
  56             server settings. If you pass <constant>NULL</constant> for this
  57             parameter, a generic <classname>Zend_Http_Client</classname> object is created.
  58         </para>
  59
  60         <para>
  61             The optional fifth parameter is a short string that Google Data
  62             servers use to identify the client application for logging
  63             purposes. By default this is string "Zend-ZendFramework";
  64         </para>
  65
  66         <para>
  67             The optional sixth parameter is a string ID for a
  68             <trademark>CAPTCHA</trademark> challenge that has been issued by
  69             the server. It is only necessary when logging in after receiving
  70             a <trademark>CAPTCHA</trademark> challenge from a previous
  71             login attempt.
  72         </para>
  73
  74         <para>
  75             The optional seventh parameter is a user's response to a
  76             <trademark>CAPTCHA</trademark> challenge that has been issued by
  77             the server. It is only necessary when logging in after receiving
  78             a <trademark>CAPTCHA</trademark> challenge from a previous
  79             login attempt.
  80         </para>
  81
  82         <para>
  83             Below is an example of <acronym>PHP</acronym> code for a web application
  84             to acquire authentication to use the Google Calendar service
  85             and create a <classname>Zend_Gdata</classname> client object using that authenticated
  86             <classname>Zend_Http_Client</classname>.
  87         </para>
  88
  89         <programlisting language="php"><![CDATA[
  90 // Enter your Google account credentials
  91 $email = 'johndoe@gmail.com';
  92 $passwd = 'xxxxxxxx';
  93 try {
  94    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $passwd, 'cl');
  95 } catch (Zend_Gdata_App_CaptchaRequiredException $cre) {
  96     echo 'URL of CAPTCHA image: ' . $cre->getCaptchaUrl() . "\n";
  97     echo 'Token ID: ' . $cre->getCaptchaToken() . "\n";
  98 } catch (Zend_Gdata_App_AuthException $ae) {
  99    echo 'Problem authenticating: ' . $ae->exception() . "\n";
 100 }
 101
 102 $cal = new Zend_Gdata_Calendar($client);
 103 ]]></programlisting>
 104     </sect2>
 105
 106     <sect2 id="zend.gdata.clientlogin.terminating">
 107         <title>Terminating a ClientLogin authenticated Http Client</title>
 108
 109         <para>
 110             There is no method to revoke ClientLogin authentication as there
 111             is in the AuthSub token-based solution. The credentials used
 112             in the ClientLogin authentication are the login and password
 113             to a Google account, and therefore these can be used repeatedly
 114             in the future.
 115         </para>
 116     </sect2>
 117 </sect1>