Google Authenticator integration guide

Identity Engine

This guide shows you how to integrate Google Authenticator into your authentication use cases using the embedded SDK.

---

Learning outcome

Understand the Google Authenticator flow

What you need

• Identity Engine SDK set up for your own app

• Google Authenticator installed on a mobile device

Sample code

Embedded Javascript SDK sample application (opens new window)

---

Why choose Google Authenticator

Google Authenticator is an authenticator app developed by Google that's used to verify the identity of a user. The app is often used with a password to strengthen user accounts from security attacks. This approach is considered more secure than other authenticators such as SMS. It's resistant to SIM swap attacks, and it doesn't require a cellular or wireless network to use. Setup can be as easy as a snapshot of a QR Code.

Authentication flow

After a user is enrolled in Google Authenticator, the service provider (for example, a website) presents a challenge. The challenge asks for a time-based one-time passcode (TOTP) during authentication. Google Authenticator generates the TOTP, and the user submits it to the service provider for verification. The service provider independently generates the password and validates that the submitted password is identical to the generated one.

A shared key linking the Google Authenticator app and service provider allows for both entities to generate the same password. The service provider generates the shared key. Then the service provider adds the key to the app during enrollment.

As the service provider, you can provide Google Authenticator support to your users. Enable Google Authenticator in your Okta org. Use the embedded SDK to build support for it in your app.

The following diagram illustrates how the Google Authenticator enrollment and challenge flows can work in your application.

Update configurations

Before you can start using Google Authenticator, create an Okta org application as described in

An Okta org already configured for a password-only use case

. Then add Google Authenticator to your app integration by executing the following steps:

Add Google Authenticator to your org

First, add Google Authenticator to your org and enable it.

1. Open the Admin Console for your org.
2. Choose Security > Authenticators to show the available authenticators.
3. If the Google Authenticator isn't in the list:
   1. Click Add Authenticator.
   2. Click Add on the Google Authenticator tile, and then click Add in the next dialog.
4. Select the Enrollment tab.
5. Check that Google Authenticator is set to either Optional or Required in the Eligible Authenticators section of the default policy.
   1. If Google Authenticator is set to Disabled, click Edit for the default policy
   2. Select Optional from the dropdown box for the Google Authenticator, and then click Update Policy.

Set your app integration to use Google Authenticator

New apps are automatically assigned the shared default authentication policy (opens new window). This policy has a catch-all rule that allows a user access to the app using either one or two factors, depending on your org setup. In production, it becomes evident when you can share your authentication needs between apps. Okta recommends that you create a policy specifically for your app for testing purposes.

1. Open the Admin Console for your org.

2. Choose Security > Authentication Policies to show the available authentication policies.

3. Click Add a Policy.

4. Give the policy a name, and then click Save.

5. Locate the catch-all rule of the new policy and select Actions > Edit.

6. Select Allowed after successful authentication.

7. Set User must authenticate with to Password + Another factor.

8. For Possession factor constraints

   1. Verify that Device Bound is selected.
   2. Verify that Google Authenticator is listed in the box under Additional factor types. If it isn't listed, check that the authenticator has been enabled using steps 4 and 5 of Add Google Authenticator to your org.
   3. Click Save.

9. Select the Applications tab for your newly created policy, and then click Add App.

10. Find your app in the list and click Add next to it.

11. Click Close.

12. Verify that the app is now listed in the Applications tab of the new policy.

Install Google Authenticator

Install the Google Authenticator app on your mobile device using either the Google Play (Android) or the Apple App Store (iOS).

Integrate SDK for authenticator enrollment

Summary of enrollment flow

The following summarizes the Google Authenticator enrollment flow using a user sign-in use case.

Initiate use case requiring authentication

The first step is to initiate a use case that requires authentication. This guide uses a sign-in with username and password flow that is initiated with a call to OktaAuth.idx.authenticate().

  const transaction = await authClient.idx.authenticate({
    username,
    password,
  });

Display Google Authenticator option

If you configure your Okta org as detailed in Configuration updates, authenticate() returns a response with Google Authenticator in the list of available authenticators. Specifically, IdxTransaction is returned with a status of PENDING, nextStep.name set to select-authenticator-enroll, and Google Authenticator is included as an option in the nextStep.options array. See the following IdxTransaction example.

{
  status: "PENDING",
  nextStep: {
    name: "select-authenticator-enroll",
    inputs: [
      {
        name: "authenticator",
        key: "string",
      },
    ],
    options: [
      {
        label: "Google Authenticator",
        value: "google_otp",
      }
    ],
  },
}

Use the value and label properties to show the available list of authenticators to the user. The sample app constructs a dropdown list using a Mustache (opens new window) template.

  <select id="authenticator-options" class="ui selection dropdown" name="authenticator">
    {{#options}}
      <option value="{{value}}">{{label}}</option>
    {{/options}}
  </select>

UI showing the Google Authenticator option:

Submit Google Authenticator option

When the user selects and submits Google Authenticator, call OktaAuth.idx.proceed() and passes in the google_otp value from IdxOption.value.

    const transaction = await authClient.idx.proceed({ authenticator });
    handleTransaction({ req, res, next, authClient, transaction });

Display shared secret and QR Code

Next, display the shared secret to the user so they can copy the value to the Google Authenticator app. The response from OktaAuth.idx.proceed() allows you to display a string and QR code that contains the shared secret. IdxTransaction is returned with authenticator.contextualData.sharedsecret set to a string of the secret and authenticator.contextualData.qrcode.href stores the secret in a Base64-encoded PNG image. See the following IdxTransaction example.

{
  status: "PENDING",
  nextStep: {
    name: "enroll-authenticator",
    inputs: [
      {
        name: "verificationCode",
        ...
      },
    ],
    type: "app",
    authenticator: {
      contextualData: {
        qrcode: {
          method: "embedded",
          href: "data:image/png;base64,iVBORw0KGgoAAAANSUh ... ",
          type: "image/png",
        },
        sharedSecret: "6BCSPLSQTAYWOCDX",
      },
      ...
    },
  },
}

The following Mustache (opens new window) template snippet shows how the sample app displays the QR code and shared secret string.

    <div class="ui segment">
      {{#contextualData.qrcode}}
        <div class="ui fluid image">
          <img id="authenticator-qr-code" src="{{contextualData.qrcode.href}}" />
        </div>
      {{/contextualData.qrcode}}
    </div>
    <div class="ui segment">
      {{#contextualData.sharedSecret}}
        <div class="ui label">SharedSecret: </div>
        <p id="authenticator-shared-secret">{{contextualData.sharedSecret}}</p>
      {{/contextualData.sharedSecret}}
    </div>

Example UI showing the Google Authenticator in the dropdown list:

Copy shared secret to Google Authenticator

After the shared secret appears, the user installs the Google Authenticator app on their mobile device if it's not already installed. Next, they add the secret code to the Google Authenticator app. They can either take a photo of the QR code or manually enter in the secret string. After it's added, Google Authenticator displays the time-based one-time passcode for the newly added account.

Submit one-time passcode in your app

The user then copies the one-time passcode from Google Authenticator to your app. After the user submits the password, call OktaAuth.idx.proceed() and pass in the password.

  const { verificationCode } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({ verificationCode });
  handleTransaction({ req, res, next, authClient, transaction });

Depending on how the org is configured, the returned IdxTransaction object can either return a status of PENDING or SUCCESS with access and ID tokens.

Integrate SDK for authenticator challenge

Summary of challenge flow

The following summarizes the Google Authenticator challenge flow using a user sign-in use case.

Initiate use case requiring authentication

The first step is to initiate a use case that requires authentication. This guide uses a sign-in with username and password flow that is initiated with a call to OktaAuth.idx.authenticate().

  const transaction = await authClient.idx.authenticate({
    username,
    password,
  });

Display Google Authenticator challenge

If you configure your Okta org as detailed in Configuration updates and the Google Authenticator is already enrolled for the user, authenticate() returns a response indicating that Google Authenticator is required for verification. Specifically, IdxTransaction is returned with a status of PENDING, nextStep.name set to challenge-authenticator, and nextStep.authenticator filled with Google Authenticator details. See the following IdxTransaction example.

{
  status: "PENDING",
  nextStep: {
    name: "challenge-authenticator",
    inputs: [
      {
        name: "verificationCode",
        label: "Enter code",
        required: true,
        type: "string",
      },
    ],
    type: "app",
    authenticator: {
      type: "app",
      key: "google_otp",
      id: "uftcz6l3mXfBZrngY696",
      displayName: "Google Authenticator",
      methods: [
        {
          type: "otp",
        },
      ],
    },
  },
}

Use the IdxTransaction properties to show a challenge page that displays a one-time passcode input field. The sample app constructs this page using a Mustache (opens new window) template.

<div class="field">
  <div class="ui labeled input">
    <div class="ui label">
      Enter Code
    </div>
    {{#input}}
      <input id="authenticator-code-input" type="{{type}}" name="{{name}}" autoComplete="off" required />
    {{/input}}
  </div>
</div>
<button id="submit-button" class="ui fluid large primary submit button" type="submit">
  Verify
</button>

UI showing the one-time passcode input field.

Get one-time passcode from Google Authenticator

Next, the user opens Google Authenticator on their mobile device and finds the one-time passcode for their account.

Submit one-time passcode in your app

When the user enters and submits this one-time passcode, call OktaAuth.idx.proceed() and pass in the password.

  const { verificationCode } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({ verificationCode });
  handleTransaction({ req, res, next, authClient, transaction });

Depending on how the org is configured, the returned IdxTransaction object can either return a status of PENDING or SUCCESS with access and ID tokens.

See also

• Sign-in flow with password and email factors
• Self-service registration