18.2. Authenticating with AuthSub

The AuthSub mechanism enables you to write web applications that acquire authenticated access Google Data services, without having to write code that handles user credentials.

See Http://code.google.com/apis/accounts/AuthForWebApps.HTML for more information about Google Data AuthSub authentication.

The Google documentation says the ClientLogin mechanism is appropriate for "installed applications" whereas the AuthSub mechanism is for "web applications." The difference is that AuthSub requires interaction from the user, and a browser interface that can react to redirection requests. The ClientLogin solution uses PHP code to supply the account credentials; the user is not required to enter her credentials interactively.

The account credentials supplied via the AuthSub mechanism are entered by the user of the web application. Therefore they must be account credentials that are known to that user.

	Registered applications
	`Zend_Gdata` currently does not support use of secure tokens, because the AuthSub authentication does not support passing a digital certificate to acquire a secure token.

18.2.1. Creating an AuthSub authenticated Http Client

Your PHP application should provide a hyperlink to the Google URL that performs authentication. The static function Zend_Gdata_AuthSub::getAuthSubTokenUri() provides the correct URL. The arguments to this function include the URL to your PHP application so that Google can redirect the user's browser back to your application after the user's credentials have been verified.

After Google's authentication server redirects the user's browser back to the current application, a GET request parameter is set, called token. The value of this parameter is a single-use token that can be used for authenticated access. This token can be converted into a multi-use token and stored in your session.

Then use the token value in a call to Zend_Gdata_AuthSub::getHttpClient(). This function returns an instance of Zend_Http_Client, with appropriate headers set so that subsequent requests your application submits using that Http Client are also authenticated.

Below is an example of PHP code for a web application to acquire authentication to use the Google Calendar service and create a Zend_Gdata client object using that authenticated Http Client.

$my_calendar = 'http://www.google.com/calendar/feeds/default/private/full';

if (!isset($_SESSION['cal_token'])) {
    if (isset($_GET['token'])) {
        // You can convert the single-use token to a session token.
        $session_token =
            Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
        // Store the session token in our session.
        $_SESSION['cal_token'] = $session_token;
    } else {
        // Display link to generate single-use token
        $googleUri = Zend_Gdata_AuthSub::getAuthSubTokenUri(
            'http://'. $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'],
            $my_calendar, 0, 1);
        echo "Click <a href='$googleUri'>here</a> " .
             "to authorize this application.";
        exit();
    }
}

// Create an authenticated HTTP Client to talk to Google.
$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['cal_token']);

// Create a Gdata object using the authenticated Http Client
$cal = new Zend_Gdata_Calendar($client);

18.2.2. Revoking AuthSub authentication

To terminate the authenticated status of a given token, use the Zend_Gdata_AuthSub::AuthSubRevokeToken() static function. Otherwise, the token is still valid for some time.

// Carefully construct this value to avoid application security problems.
$php_self = htmlentities(substr($_SERVER['PHP_SELF'],
                         0,
                         strcspn($_SERVER['PHP_SELF'], "\n\r")),
                         ENT_QUOTES);

if (isset($_GET['logout'])) {
    Zend_Gdata_AuthSub::AuthSubRevokeToken($_SESSION['cal_token']);
    unset($_SESSION['cal_token']);
    header('Location: ' . $php_self);
    exit();
}

Security notes

	Security notes
The treatment of the `$php_self` variable in the example above is a general security guideline, it is not specific to `Zend_Gdata`. You should always filter content you output to http headers. Regarding revoking authentication tokens, it is recommended to do this when the user is finished with her Google Data session. The possibility that someone can intercept the token and use it for malicious purposes is very small, but nevertheless it is a good practice to terminate authenticated access to any service.

The treatment of the $php_self variable in the example above is a general security guideline, it is not specific to Zend_Gdata. You should always filter content you output to http headers.

Regarding revoking authentication tokens, it is recommended to do this when the user is finished with her Google Data session. The possibility that someone can intercept the token and use it for malicious purposes is very small, but nevertheless it is a good practice to terminate authenticated access to any service.