Net::G...uthSub(3pm)

💖 Net::Google::AuthSub 💖

okay so bestie, welcome to the Net::Google::AuthSub(3pm) page — that's the one sitting in the User Contributed Perl Documentation section of your manual 💅. This little icon lets you talk to sites that do Google-style AuthSub, and honestly? she's giving "old but gold" 🫶.

---

🌸 NAME 🌸

Net::Google::AuthSub — interact with sites that implement Google style AuthSub ✨

---

🎀 SYNOPSIS 🎀

like, here's the whole vibe in one go, no cap:

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, so it's lowkey everywhere.

You can read more about it here, bestie:

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

A Google Group for AuthSub is here too:

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

---

💀 DEALING WITH CAPTCHAS 💀

So here's the situation: if a login response fails then it may set the error code to 'CaptchRequired', and the response object will let you 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. (yes bestie, that's literally what it says, i'm just the messenger 😭)

🦋 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

---

and that's the whole page, bestie 🫶 this one's shipping out of perl v5.36.0, dated 2022-10-13, under the name Net::G...uthSub(3pm) — go forth and authenticate slayfully 💅✨