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

Sample ASP.NET MVC Application using Embedded Authentication with the IDX SDK (opens new window)

---

Why choose Google Authenticator

Google Authenticator is an authenticator app developed by Google 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 because it's resistant to SIM swap attacks. It doesn't require a cellular or wireless network to use and 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 to provide a time-based one-time passcode (TOTP) during authentication. Google Authenticator generates the TOTP, which the user submits 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 and adds it 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 and use the embedded SDK to build support for it in your application.

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 either using either the Google Play Store (Android) or Apple App Store (iOS).

Integrate SDK for authenticator enrollment

Summary of steps

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

1: Build a sign-in page on the client

Build a sign-in page that captures the user's name and password, as shown in the following example.

2: Authenticate the user credentials

After a user initiates the sign-in flow by entering their username and password and then clicking Sign In, create an AuthenticationOptions object in your LogIn method. Then, set the object's Username and Password properties to the values set by the user. Pass this object as a parameter to the AuthenticateAsync method on the IdxClient.

var authnOptions = new AuthenticationOptions
{
   Username = model.UserName,
   Password = model.Password,
};

try
{
   var authnResponse = await _idxClient.AuthenticateAsync(authnOptions).ConfigureAwait(false);

3: Handle the response from the sign-in flow

Query the AuthenticationStatus property of the AuthenticationResponse object returned by AuthenticateAsync to discover the current status of the authentication process.

  Session["idxContext"] = authnResponse.IdxContext;
  switch (authnResponse?.AuthenticationStatus)
  {
     case AuthenticationStatus.Success:
           … your code …
     case AuthenticationStatus.PasswordExpired:
           … your code …

If you configured your Okta org correctly, you need to respond to two specific authenticator statuses to handle this scenario in addition to Success and PasswordExpired:

• AwaitingAuthenticatorEnrollment that is covered in this section
• AwaitingChallengeAuthenticatorSelection that is covered in the challenge flow section.

The names of the authenticators available for enrollment or challenge can be found in the AuthenticationResponse object's Authenticators collection. Redirect the user to a list of authenticators to select the Google Authenticator for enrollment.

Note: The isChallengeFlow session variable is set to false if the user needs to enroll Google Authenticator first, and true if they have already done so.

      case AuthenticationStatus.AwaitingAuthenticatorEnrollment:
         Session["isChallengeFlow"] = false;
         Session["authenticators"] = 
            ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
         return RedirectToAction("SelectAuthenticator", "Manage");
      case AuthenticationStatus.AwaitingChallengeAuthenticatorSelection:
         Session["authenticators"] = 
            ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
         Session["isChallengeFlow"] = true;
         return RedirectToAction("SelectAuthenticator", "Manage");
      default:
         return View("Login", model);
   }
}
catch (OktaException exception)
{
   ModelState.AddModelError(string.Empty, $"Invalid login attempt: {exception.Message}");
   return View("Login", model);
}

4: Display a list of possible authenticator factors

Build a page to display the list of authenticators (including Google Authenticator). For example, in the sample application, a new SelectAuthenticatorViewModel is populated from the Authenticators collection returned by the AuthenticationResponse in the previous step.

public ActionResult SelectAuthenticator()
{
   var authenticators =
      (IList<AuthenticatorViewModel>)Session["authenticators"] ??
      new List<AuthenticatorViewModel>();

   var viewModel = new SelectAuthenticatorViewModel
   {
      Authenticators = authenticators,
      AuthenticatorId = authenticators.
         FirstOrDefault()?.AuthenticatorId,
      PasswordId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "password")?.AuthenticatorId,
      PhoneId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "phone")?.AuthenticatorId,
      WebAuthnId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "security key or biometric")?.AuthenticatorId,
      TotpId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "google authenticator")?.AuthenticatorId,
      OktaVerifyId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "okta verify")?.AuthenticatorId,
      CanSkip = TempData["canSkip"] != null && (bool)TempData["canSkip"]
   };

   return View(viewModel);
}

The viewModel parameter is then consumed in a Razor page.

<section id="selectAuthenticatorForm">
   @using (Html.BeginForm("SelectAuthenticatorAsync", "Manage",
      new { ReturnUrl = ViewBag.ReturnUrl }, FormMethod.Post,
      new { @class = "form-horizontal", role = "form" }))
   {
      @Html.AntiForgeryToken()
      <!-- Headings elided -->
      @Html.ValidationSummary(true, "", new { @class = "text-danger" })
      @Html.HiddenFor(m => m.PasswordId)
      @Html.HiddenFor(m => m.PhoneId)
      @Html.HiddenFor(m => m.WebAuthnId)
      @Html.HiddenFor(m => m.OktaVerifyId)
      @Html.HiddenFor(m => m.TotpId)
      <ul>
         @foreach (var authenticator in Model.Authenticators)
         {
            <div>
               <label>
                  @Html.RadioButtonFor(m => m.AuthenticatorId,
                     authenticator.AuthenticatorId)
                  @authenticator.Name
               </label>
            </div>
         }
      </ul>
      @Html.ValidationMessageFor(m => m.AuthenticatorId, 
         "", new { @class = "text-danger" })
      <div>
         <div>
            <input type="submit" value="Submit" />
         </div>
      </div>
   }
</section>

In this use case, only Google Authenticator appears, as shown in the following screenshot.

5: Retrieve shared secret and QR Code

When the user selects the Google Authenticator factor and clicks Submit, the form posts back to the SelectAuthenticatorAsync method. This checks whether the user is in challenge flow or enrollment flow.

When in Enrollment flow, a call is made to idxClient.SelectEnrollAuthenticatorAsync, using its enrollAuthenticatorOptions parameter to pass in the Google Authenticator factor ID.

var enrollAuthenticatorOptions = new SelectEnrollAuthenticatorOptions
{
   AuthenticatorId = model.AuthenticatorId,
};

var enrollResponse = await _idxClient.SelectEnrollAuthenticatorAsync(
    enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

If the call is successful, the returned enrollResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification and its CurrentAuthenticator property contains the QR code and shared secret string that the user can use to setup their copy of the Google Authenticator app. This needs to be passed to a page to display that information.

Session["IdxContext"] = enrollResponse.IdxContext;
Session["isPasswordSelected"] = model.IsPasswordSelected;

switch (enrollResponse?.AuthenticationStatus)
{
   case AuthenticationStatus.AwaitingAuthenticatorVerification:
      {
         if (model.IsPasswordSelected)
         {
            return RedirectToAction("ChangePassword", "Manage");
         }
         else if (model.IsTotpSelected)
         {
            Session["currentWebAuthnAuthenticator"] = 
               enrollResponse.CurrentAuthenticator;
            return RedirectToAction(
               "EnrollGoogleAuthenticator", "Manage");
         }

         return RedirectToAction("VerifyAuthenticator", "Manage");
      }

  // other case statements

   default:
      return View("SelectAuthenticator", model);
}

6: Display shared secret and QR code

Build a page to display the shared secret and QR code. For example, in the sample application, a new EnrollGoogleAuthenticatorViewModel is populated from the CurrentAuthenticator object returned by the enrollResponse object in the previous step.

public ActionResult EnrollGoogleAuthenticator()
{
   var currentAuthenticator = (IAuthenticator)Session["currentWebAuthnAuthenticator"];
   var model = new EnrollGoogleAuthenticatorViewModel
   {
      QrCodeHref = currentAuthenticator.ContextualData.QrCode.Href,
      SharedSecret = currentAuthenticator.ContextualData.SharedSecret,
   };

   return View(model);
}

This ViewModel is then consumed in a Razor page

<div>
   @using (Html.BeginForm("EnrollGoogleAuthenticatorAsync", "Manage",
      FormMethod.Post, new { role = "form" }))
   {
      @Html.AntiForgeryToken()
      <h4>Set up Google Authenticator</h4>

      <hr />
      <div>
         <img id="qrCodeImg" src = @Model.QrCodeHref />
      </div >
      <div>
         <div>
            @Html.LabelFor(m => m.SharedSecret)
         </div>
         <div>
            @Html.EditorFor(m => m.SharedSecret)
         </div>
      </div>
      <div>
         <input type="submit" value="Next" />
      </div>
   }
</div>

The user sees the following

7: 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 by either taking a photo of the QR code or manually entering the secret string. Once added, Google Authenticator displays the time-based one-time passcode (TOTP) for the newly added account.

8: Display challenge page

Build a form that allows the user to enter the TOTP they have received from their Authenticator app. This should appear once the user clicks on the Next button underneath the QR code and sample secret.

@using (Html.BeginForm("VerifyAuthenticatorAsync", "Manage",
   new { ReturnUrl = ViewBag.ReturnUrl }, FormMethod.Post, new { role = "form" }))
{
   @Html.AntiForgeryToken()
   <h4>Verify authenticator.</h4>
   <h5>Enter the passcode to continue.</h5>
   <hr />
   @Html.ValidationSummary(true, "", new { @class = "text-danger" })
   <div>
      <div>
         <div>
            @Html.LabelFor(m => m.Code)
         </div>
         <div>
            @Html.TextBoxFor(m => m.Code, new { @id="passcodeInput" })
            @Html.ValidationMessageFor(m => m.Code, "", new { @class = "text-danger" })
         </div>
      </div>
   </div>

   <div>
      <div>
         <input type="submit" value="Submit"  id="submitBtn" />
      </div>
   </div>
}

The user sees the following:

9: Process the one-time passcode

Once a user has entered the TOTP and clicked Submit, create a VerifyAuthenticatorOptions object and set its Code property to the password entered by the user. Pass this object as a parameter to the IdxClient.VerifyAuthenticatorAsync method.

var verifyAuthenticatorOptions = new VerifyAuthenticatorOptions
{
   Code = code,
};

try
{
   var authnResponse = await _idxClient.VerifyAuthenticatorAsync(
      verifyAuthenticatorOptions, (IIdxContext)Session["idxContext"]);

Query the AuthenticationStatus property of the AuthenticationResponse object returned by VerifyAuthenticatorAsync to discover the current status of the authentication process. You need to respond to two specific authenticator statuses:

• AwaitingPasswordReset
• Success

On success, call AuthenticationHelper.GetIdentityFromTokenResponseAsync to retrieve the OIDC claims information about the user and pass them into your application. The user has now logged in.

   Session["idxContext"] = authnResponse.IdxContext;

   switch (authnResponse.AuthenticationStatus)
   {
      case AuthenticationStatus.AwaitingPasswordReset:
         return RedirectToAction("ChangePassword", "Manage");

      case AuthenticationStatus.Success:
         ClaimsIdentity identity = await AuthenticationHelper.GetIdentityFromTokenResponseAsync(
             _idxClient.Configuration, authnResponse.TokenInfo);
         _authenticationManager.SignIn(new AuthenticationProperties(), identity);
         return RedirectToAction("Index", "Home");
   }

   return View(view, model);
}
catch (OktaException exception)
{
   ModelState.AddModelError(string.Empty, exception.Message);
   return View(view, model);
}

Integrate SDK for authenticator challenge

Summary of steps

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

1 - 4: Start flow and display authenticator list

The challenge flow follows the same first four steps as the enrollment flow:

• Build a sign-in page on the client
• Authenticate the user credentials
• Handle the response from the sign-in flow
• Display a list of possible authenticator factors

5: Check Authenticator Status

When the user selects Google Authenticator to authenticate themselves and clicks Submit, the application checks whether the user is in challenge flow or in enrollment flow by posting back to SelectAuthenticatorAsync.

When in challenge flow, a call is made to idxClient.SelectChallengeAuthenticatorAsync, using its selectAuthenticatorOptions parameter to pass in the Google Authenticator factor ID.

var selectAuthenticatorOptions = new SelectAuthenticatorOptions
{
    AuthenticatorId = model.AuthenticatorId,
};

selectAuthenticatorResponse = await _idxClient.SelectChallengeAuthenticatorAsync(
    selectAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

If the call is successful, the returned selectAuthenticatorResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification, and the Challenge page should appear.

Session["IdxContext"] = selectAuthenticatorResponse.IdxContext;

switch (selectAuthenticatorResponse?.AuthenticationStatus)
{
    case AuthenticationStatus.AwaitingAuthenticatorVerification:
        var action = (model.IsWebAuthnSelected)
            ? "VerifyWebAuthnAuthenticator"
            : "VerifyAuthenticator";
        if (model.IsWebAuthnSelected)
        {
            Session["currentWebAuthnAuthenticator"] =
                selectAuthenticatorResponse.CurrentAuthenticatorEnrollment;
        }
        return RedirectToAction(action, "Manage");

    // other case statements

    default:
        return View("SelectAuthenticator", model);
}

6: Get one-time passcode from Google Authenticator

The user’s copy of Google Authenticator now displays the time-based one-time passcode for the newly added account which they will enter into a challenge page.

7 - 8: Display challenge page and process passcode

The challenge flow now follows the same final steps as the Enrollment flow:

• Display challenge page
• Process the one-time passcode

See also

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