Rajat

Looking for my next remote gig. I'd love to chat. Drop me a mail.

How To Implement Google Authenticator Two Factor Auth in JavaScript

Google Authenticator is something that many of us use all the time but how many of us really understand how it works under the hood?
In this tutorial, I will demystify the magic behind Google Authenticator’s expiring OTP codes and show you how to add Google Authenticator support to your application from scratch, in JavaScript.
As part of Pesto’s career accelerator program, I got an opportunity to contribute to this amazing open-source project called Enquirer. It lets you create stylish command line prompts that are user-friendly and easy to create. At the time of writing this article, Enquirer has upwards of 4500 Github stars and is used by more than 7500 other repositories. 
One of the features I added to Enquirer was the ability to verify time-based one-time passwords, directly from command-line, generated by any two-factor authentication application, such as Google Authenticator, without the need of an internet connection.


Why Time-based OTPs?

Time-based OTP (TOTP) is an algorithm that factors in the current time to generate a unique one-time password.
In today’s age, it is a no-brainer that passwords alone can’t keep the bad guys out. You need an additional layer of security — a second factor.
There are many types of two-factor authentication systems, but for them to work, they must be both secure and user-friendly. TOTP ticks both boxes perfectly.
It’s secure because:
  • The password changes every n number of seconds (usually, 30 seconds), preventing eavesdroppers from using that same password later in the future if somehow they’re able to get hold of it.
  • The password may be generated by an app on the user’s phone, making it more difficult for an attacker to acquire the password, as the user’s phone is usually by his/her side.
It’s user-friendly because:
  • In mobile app implementations, the user only needs to launch the TOTP application and then key-in the TOTP that appears on-screen into the application
  • Unlike most mobile-based one-time passwords that need to be received via a text message or the Internet through some wireless connection, TOTPs aren’t dependent on the presence of a cellular signal or data connection.
I used Google Authenticator as the mobile app to verify one-time passwords.
Google Authenticator generates time-based OTPs which are calculated using the algorithm specified in RFC6238. The app also supports HMAC-based OTPs calculated using the algorithm specified in RFC4226
Time-based OTPs rely on the algorithm for HMAC-based OTPs (HOTPs). In this article, we’ll be implementing both the algorithms, using NodeJS (JavaScript).

Generating Secret

Firstly, we’ll have to create an application-specific secret key that will be used to verify OTPs. This will also be shared with the Google Authenticator app.
The secret key is how the authenticator apps know what OTPs to generate for a specific app/website. The secret can be generated in many ways and this is one of the implementations.
We’ll generate a completely random buffer of data using the in-built
crypto
NodeJS library and then we’ll encode the data to base32 using
hi-base32
npm module.
const crypto = require('crypto');
const base32 = require('hi-base32');

function generateSecret(length = 20) {
   const randomBuffer = crypto.randomBytes(length);
   return base32.encode(randomBuffer).replace(/=/g, '');
}
This function will return a random string which is our secret key. 
Input this in the Google Authenticator app. We’ll be verifying the OTPs for this secret, using our implementation.

Generating HMAC-based OTPs

To generate HOTP we need a secret key and a counter value. We already have a secret. We don’t need to worry about counter as of now because we’ll be providing its value when we generate TOTPs.
Basics
Let’s say our function that generates HOTP accepts two arguments,
secret
and
counter
. First, we’ll decode the secret.
const decodedSecret = base32.decode.asBytes(secret);
Now we’ll create a buffer from the
counter
value.
const buffer = Buffer.alloc(8);
for (let i = 0; i < 8; i++) {
   buffer[7 - i] = counter & 0xff;
   counter = counter >> 8;
}
According to RFC4226, we have three major steps to generate a HOTP.
Step 1 — Generate an HMAC value
Google Authenticator uses SHA1 algorithm to create HMAC. We’ll use functions from the
crypto
library to create an HMAC (using SHA1), update the above-created
buffer
with this and then produce an HMAC value;
const hmac = crypto.createHmac('sha1', Buffer.from(decodedSecret));
hmac.update(buffer);
const hmacResult = hmac.digest();
hmacResult
is a 20-byte string which is an HMAC-SHA-1 value.
Step 2 — Dynamic Truncation
The purpose of dynamic truncation is to extract 4-byte dynamic binary code from a 20-byte HMAC-SHA-1 result. These steps are directly taken from RFC4226.
const offset = hmacValue[hmacValue.length - 1] & 0xf;
const code = ((hmacValue[offset] & 0x7f) << 24) |
             ((hmacValue[offset + 1] & 0xff) << 16) |
             ((hmacValue[offset + 2] & 0xff) << 8) |
             (hmacValue[offset + 3] & 0xff);
Step 3 — Compute the HOTP value
Google Authenticator generates six-digit passwords, so we’ll extract the first six-digits of the
code
to get our final HOTP value.
const hotp = code % (10 ** 6);
Putting it all together, the generateHOTP function can be written as:
const crypto = require('crypto');
const base32 = require('hi-base32');

function generateHOTP(secret, counter) {
   const decodedSecret = base32.decode.asBytes(secret);
   const buffer = Buffer.alloc(8);
   for (let i = 0; i < 8; i++) {
      buffer[7 - i] = counter & 0xff;
      counter = counter >> 8;
   }

   // Step 1: Generate an HMAC-SHA-1 value
   const hmac = crypto.createHmac('sha1', Buffer.from(decodedSecret));
   hmac.update(buffer);
   const hmacResult = hmac.digest();
 
   // Step 2: Generate a 4-byte string (Dynamic Truncation)
   const code = dynamicTruncationFn(hmacResult);

   // Step 3: Compute an HOTP value
   return code % 10 ** 6;
}

function dynamicTruncationFn(hmacValue) {
   const offset = hmacValue[hmacValue.length - 1] & 0xf;

   return (
      ((hmacValue[offset] & 0x7f) << 24) |
      ((hmacValue[offset + 1] & 0xff) << 16) |
      ((hmacValue[offset + 2] & 0xff) << 8) |
      (hmacValue[offset + 3] & 0xff)
   );
}
We have a function using which we can generate HMAC based one-time passwords. Now we can use this function to generate Time based one-time passwords.

Generating Time-based OTPs

The algorithm for time-based OTPs simply uses current Unix time (with a time-step of 30 seconds) as the
counter
value in the
generateHOTP
function.
We can get the current time in JavaScript using
Date.now()
. But this returns the number of milliseconds elapsed since
January 1, 1970, 00:00:00 UTC
. We have to convert the time-step of 1 millisecond to time-step of 30 seconds.
const counter = Math.floor(Date.now() / 30000);
We also accept a
window
argument which helps us get the TOTP of any time window from current time. So if we want to know what TOTP was generated before 2 minutes from now, we set
window = -4
. This calculates the TOTP at 4 time-steps (of 30 seconds each) before the current time.
So, our
generateTOTP
function can be written as:
function generateTOTP(secret, window = 0) {
   const counter = Math.floor(Date.now() / 30000);
   return generateHOTP(secret, counter + window);
}

Verifying Time-based OTPs

To verify TOTPs generated on the Google Authenticator app, we need the secret key. Once we have the secret key we can use the
generateTOTP
function above and calculate the TOTP to see if it matches or not.
Sometimes, it is possible that while a user is typing the OTP the current window of 30 seconds passes and the OTP she entered gets failed. To improve the user experience, we not only check the TOTP generated at the current time-step window but also one step before and one step after the current window. 
If the current time is T⁰, we'll verify the TOTP for these steps:
   T⁰ – 1
   T⁰ 
   T⁰ + 1
We can also use a wider window but doing so may be a security risk. If we use a window of
T⁰ ± 20
, for example, this would mean that an OTP generated 10 minutes ago is still valid!
Keeping this in mind, our
verifyTOTP
function can be written as:
function verifyTOTP(token, secret, window = 1) {
   if (Math.abs(+window) > 10) {
      console.error('Window size is too large');
      return false;
   }

   for (let errorWindow = -window; errorWindow <= +window; errorWindow++) {
      const totp = generateTOTP(secret, errorWindow);
      if (token === totp) {
         return true;
      }
   }

   return false;
}
token
is the TOTP from Google Authenticator. We are invoking
generateTOTP
function to calculate the TOTPs for all windows and checking if it matches with the token entered.
This function returns
true
if the token is successfully verified. This completes the implementation of Two Factor Authentication (TOTP) with Google Authenticator.
I’ve removed some error checking to keep this article simple. You can find the complete code at this pull request
Make sure you check out the Enquirer library and drop a Github star. Thanks for reading!
Hi, my name is Rajat. I am a truly full-stack software engineer with experience working on everything from patching U-boot and Linux drivers in C to launching top-rated products on Product Hunt.

Tags

Topics of interest