NAME

       Net::Google::AuthSub - interact with sites that implement Google style AuthSub

SYNOPSIS

           my $auth = Net::Google::AuthSub->new;
           my $response = $auth->login($user, $pass);

           if ($response->is_success) {
               print "Hurrah! Logged in\n";
           } else {
               die "Login failed: ".$response->error."\n";
           }

           my %params = $auth->auth_params;
           $params{Content_Type}             = 'application/atom+xml; charset=UTF-8';
           $params{Content}                  = $xml;
           $params{'X-HTTP-Method-Override'} = 'DELETE';

           my $request = POST $url, %params;
           my $r = $user_agent->request( $request );

ABOUT AUTHSUB

       AuthSub is Google's method of authentication for their web services. It is also used by
       other web sites.

       You can read more about it here.

           http://code.google.com/apis/accounts/Authentication.html

       A Google Group for AuthSub is here.

           http://groups.google.com/group/Google-Accounts-API

DEALING WITH CAPTCHAS

       If a login response fails then it may set the error code to 'CaptchRequired' and the
       response object will allow you to retrieve the "captchatoken" and "captchaurl" fields.

       The "captchaurl" will be the url to a captcha image or you can show the user the web page

           https://www.google.com/accounts/DisplayUnlockCaptcha

       Then retry the login attempt passing in the parameters "logintoken" (which is the value of
       "captchatoken") and "logincaptcha" which is the user's answer to the CAPTCHA.

           my $auth = Net::Google::AuthSub->new;
           my $res  = $auth->login($user, $pass);

           if (!$res->is_success && $res->error eq 'CaptchaRequired') {
               my $answer = display_captcha($res->captchaurl);
               $auth->login($user, $pass, logintoken => $res->captchatoken, logincaptcha => $answer);
           }

       You can read more here

           http://code.google.com/apis/accounts/AuthForInstalledApps.html#Using

METHODS

   new [param[s]]
       Return a new authorisation object. The options are

       url The base url of the web service to authenticate against.

           Defaults to "https://google.com/account"

       service
           Name of the Google service for which authorization is requested such as 'cl' for
           Calendar.

           Defaults to 'xapi' for calendar.

       source
           Short string identifying your application, for logging purposes.

           Defaults to 'Net::Google::AuthSub-<VERSION>'

       accountType
           Type of account to be authenticated.

           Defaults to 'HOSTED_OR_GOOGLE'.

       See http://code.google.com/apis/accounts/AuthForInstalledApps.html#ClientLogin for more
       details.

   login <username> <password> [opt[s]]
       Login to google using your username and password.

       Can optionally take a hash of options which will override the default login params.

       Returns a "Net::Google::AuthSub::Response" object.

   authorised
       Whether or not we're authorised.

   authorized
       An alias for authorized.

   auth <username> <token>
       Use the AuthSub method for access.

       See http://code.google.com/apis/accounts/AuthForWebApps.html for details.

   auth_token [token]
       Get or set the current auth token

   auth_type [type]
       Get or set the current auth type

       Returns either $Net::Google::AuthSub::CLIENT_LOGIN or $Net::Google::AuthSub::AUTH_SUB.

   request_token <next> <scope> [option[s]]
       Return a URI object representing the URL which the user should be directed to in order to
       aquire a single use token.

       The parameters are

       next (required)
           URL the user should be redirected to after a successful login.  This value should be a
           page on the web application site, and can include query parameters.

       scope (required)
           URL identifying the service to be accessed. The resulting token will enable access to
           the specified service only. Some services may limit scope further, such as read-only
           access.

           For example

               http://www.google.com/calendar/feed

       secure
           Boolean flag indicating whether the authentication transaction should issue a secure
           token (1) or a non-secure token (0).  Secure tokens are available to registered
           applications only.

       session
           Boolean flag indicating whether the one-time-use token may be exchanged for a session
           token (1) or not (0).

   session_token
       Exchange the temporary token for a long-lived session token.

       The single-use token is acquired by visiting the url generated by calling request_token.

       Returns the token if success and undef if failure.

   revoke_token
       Revoke a valid session token. Session tokens have no expiration date and will remain valid
       unless revoked.

       Returns 1 if success and undef if failure.

   token_info
       Call AuthSubTokenInfo to test whether a given session token is valid.  This method
       validates the token in the same way that a Google service would; application developers
       can use this method to verify that their application is getting valid tokens and handling
       them appropriately without involving a call to the Google service. It can also be used to
       get information about the token, including next URL, scope, and secure status, as
       specified in the original token request.

       Returns a "Net::Google::AuthSub::Response" object on success or undef on failure.

   auth_params
       Return any parameters needed in an HTTP request to authorise your app.

AUTHOR

       Simon Wistow <simon@thegestalt.org>

COPYRIGHT

       Copyright, 2007 - Simon Wistow

       Released under the same terms as Perl itself