Auth::GoogleAuth(3pm)

📦
version 1.10 · 4 versions
, in ubuntu stonking

💖 Auth::GoogleAuth — the manual, but make it cute 💖

okay bestie, gather round, because this is the Auth::GoogleAuth(3pm) page and it's literally about to make 2FA make sense. no cap. 🎀

✨ VERSION ✨

version 1.10 — she's serving, she's stable, she ate. 👑

🦋 SYNOPSIS 🦋

here's the whole vibe at a glance, copy-paste ready:

use Auth::GoogleAuth;

my $auth = Auth::GoogleAuth->new;

$auth = Auth::GoogleAuth->new({
    secret => 'some secret string thing',
    issuer => 'Example User',
    key_id => 'user@example.com',
});

$auth->secret();   # get/set
$auth->secret32(); # get/set
$auth->issuer();   # get/set
$auth->key_id();   # get/set

my $secret32 = $auth->generate_secret32;

my $otpauth_0 = $auth->otpauth;
my $otpauth_1 = $auth->otpauth(
    'bv5o3disbutz4tl3', # secret32
    'user@example.com', # key_id
    'Example User',   # issuer
);

my $url_0 = $auth->qr_code;
my $url_1 = $auth->qr_code(
    'bv5o3disbutz4tl3', # secret32
    'user@example.com', # key_id
    'Example User',   # issuer
);
my $url_2 = $auth->qr_code(
    'bv5o3disbutz4tl3', 'user@example.com', 'Example User', 1,
);

my $code_0 = $auth->code;
my $code_1 = $auth->code( 'utz4tl3bv5o3disb', 1438643789, 30 );

my $verification_0 = $auth->verify('879364');
my $verification_1 = $auth->verify(
    '879364',           # code
    1,                  # range
    'utz4tl3bv5o3disb', # secret32
    1438643820,         # timestamp (defaults to now)
    30,                 # interval (default 30)
);

$auth->clear;

🌸 DESCRIPTION 🌸

so basically? this module is the chill, simplified interface for doing typical two-factor authentication (aka "2FA", you know, the thing your bank keeps yelling at you about) with Google Authenticator. link drop: https://en.wikipedia.org/wiki/Google_Authenticator — using the TOTP Algorithm, https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm, as defined by RFC 6238, http://tools.ietf.org/html/rfc6238.

and the tea is: Google Authenticator lowkey supports both TOTP and HOTP, but right now, at this exact moment, this module only supports TOTP. that's it, that's the limitation, we're being honest about it. 💅

👑 METHODS 👑

these are the methods this module is serving:

🧚 new

a simple instantiator, and you can hand her some optional default values if you're feeling generous:

my $auth = Auth::GoogleAuth->new;

$auth = Auth::GoogleAuth->new({
    secret => 'some secret string thing',
    issuer => 'Example User',
    key_id => 'user@example.com',
});

the object she gives you back supports these attribute get/set methods, and yes they're all get/set, they're multitalented:

  • secret — this can be literally any string. it gets used as the internal secret key to make the QR codes and the authentication codes. it's giving ✨foundation✨.
  • secret32 — a base-32 encoded copy of the secret string. here's the important bit: if you leave this undefined and then run one of the methods that needs it (like qr_code or code), the method you called will try to create the secret32 by looking for a value in secret. and if none exists? a random secret32 gets generated for you. she's self-sufficient like that. 🙈
  • issuer — the label name of the "issuer" of the authentication. more info lives at the key URI format wiki page: https://github.com/google/google-authenticator/wiki/Key-Uri-Format.
  • key_id — the label name of the "key ID" of the authentication. same wiki page, same link: https://github.com/google/google-authenticator/wiki/Key-Uri-Format.

🎀 generate_secret32

this one generates a reasonable random secret32 value, stores it in the get/set method, and returns it. triple threat behavior fr fr.

my $secret32 = $auth->generate_secret32;

🌈 otpauth

returns a generated otpauth key URI. iconic.

my $otpauth_0 = $auth->otpauth;
my $otpauth_1 = $auth->otpauth(
    'bv5o3disbutz4tl3', # secret32
    'user@example.com', # key_id
    'Example User',     # issuer
);

🍓 qr_code

this method returns a Quick Chart API URL that will return a QR code, based on the data either already in the object or provided to this method. your phone camera is about to get a whole lot of attention. 📱

my $url_0 = $auth->qr_code;
my $url_1 = $auth->qr_code(
    'bv5o3disbutz4tl3', # secret32
    'user@example.com', # key_id
    'Example User',     # issuer
);

and you can optionally add a final true value. do that and the method returns the generated otpauth key URI instead of the Quick Chart API URL. two modes, one method, we love a plot twist:

my $url_2 = $auth->qr_code(
    'bv5o3disbutz4tl3', 'user@example.com', 'Example User', 1,
);

💜 code

returns an authentication code, exactly as if you were using Google Authenticator (https://en.wikipedia.org/wiki/Google_Authenticator) with the secret32 value. the six little digits. the moment of truth.

my $code_0 = $auth->code;

you can optionally pass override values, similar to qr_code:

my $code_1 = $auth->code(
    'utz4tl3bv5o3disb', # secret32
    1438643789,         # timestamp (defaults to now)
    30,                 # interval (default 30)
);

🔥 verify

this is the one that checks codes a user typed in. pass in the code (required, bestie, don't skip it) and optionally a range value plus any override values.

my $verification_0 = $auth->verify('879364');

now, about that range value, because this is the part that actually matters: the algorithm checks codes that are time-based. so if the clocks aren't exactly in sync, it's totally possible that a "nearly valid" code gets entered, and it should be accepted as valid, but it'll be seen as invalid instead. 😭 by passing in an integer as a range value you get to stipulate how "fuzzy" the time is allowed to be. the default range is 0. a value of 1 means a code based on a time 1 iteration plus or minus should verify. tiny bit of grace, huge difference.

my $verification_1 = $auth->verify(
    '879364',           # code
    1,                  # range
    'utz4tl3bv5o3disb', # secret32
    1438643820,         # timestamp (defaults to now)
    30,                 # interval (default 30)
);

🫶 clear

since the secret and secret32 values may just... sit there persisting in this object, which could honestly be a bad idea in some contexts (no shade, just facts), this clear method lets you wipe out all attribute values. clean slate, new era. 🧼

$auth->clear;

⭐ TYPICAL USE-CASE ⭐

okay so here's what this looks like in real life. typically you're gonna either randomly generate a secret or a secret32 (generate_secret32) for a user and store it, or you use a specific value or a hash of some value as the secret. either way, once you've got a secret and it's stored, generate a QR code (qr_code) for the user. alternatively you can hand the secret32 straight to the user so they can manually type it in themselves. that's it. setup done. slay. ✨

to authenticate, present the user with a way to give you a code (which will be a series of 6-digits). verify that code (verify) with either no range or some small range like 1. and that's the whole 2FA journey, bestie. 🌈

🌻 SEE ALSO 🌻

you can look for additional info about this module at:

and you can look for additional info about things related to this module at:

💌 AUTHOR 💌

Gryphon Shafer <gryphon@goldenguru.com>

This software is Copyright (c) 2015-2050 by Gryphon Shafer.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

and that's a wrap! 🎬 this whole page came to you from the User Contributed Perl Documentation, running on perl v5.40.1, dated 2026-07-05. thanks for reading, bestie, now go set up your 2FA 💖✨🔐

📦 where this page comes from