This guide assumes existing familiarity with GoScript.  If you have not used GoScript before then it is recommended to start with our basic GoScript Guide: A Guide to GoScript.

Overview

The process for setting up an authentication GoScript using TOTP is as follows:

1. Register an account with the target application and log in to the point where you are asked to enrol in TOTP MFA.
2. Note down the TOTP secret.  In most cases this will be displayed in the GUI near the QR code, it will be a long, random looking string.
   

   If you do not know the TOTP secret for your account, see Getting the Secret

3. Enrol in the MFA system using a 3rd party tool or app and finish logging in manually, so that when the scanner tries to log in it is not asked to enrol again. 
4. In GoScript:
   1. Import AppCheck's Authentication Utilities for GoScript
   2. Log in to the point where you're asked for the MFA code.
   3. Pass the Secret to AppCheck's TOTP function (part of the Authentication Utilities) and type the resulting code into the MFA form.
   4. Finish the sign-in process.

Detailed Guide

At the start of your script use the following command to import AppCheck's Authentication Utilities:

import util.auth

This makes varius functions relating to authentication available for use in your GoScript.

When the time comes to type in the MFA code, you can now use the TOTP function to get the current TOTP code based on the TOTP secret:

oneTimePassword := util.auth.get_unique_totp: [TOTP Secret]

The above command creates a variable in your script called oneTimePassword, which you can then use to fill in the appropriate box in your login form, for example if the field on your form is called "otp", then you would fill it in with this command:

otp = {oneTimePassword}

Example

A complete example script, where the secret is provided in the variable {secret} (see GoScript Variables):

import util.auth

def auth.login
  go: https://scanner.appcheck-ng.com
  wait for: AppCheck Login

  username = {username}
  password = {password}
  click: Agree to Terms and Conditions
  click: Login 
  wait for: Google Authenticator

  oneTimePassword := util.auth.get_unique_totp: {secret}
  otp = {oneTimePassword}
  click: verify
  wait for: Log out

Getting the Secret

You need to know the TOTP secret for your account in order to log in using GoScript.  If you already have the secret stored (in text form) then you have everything you need - you do not need to reset it even if you are already using it in an authenticator app.  However, if you do not know the secret you will need to find it out or reset it.

Most MFA systems will only show you the secret once, when you first "enrol" in the system.  They will usually show it in the form of a QR code, sometimes with the option of viewing it as text.

If you haven't yet enrolled, go through the process once manually, noting down the secret as you do.  You will need to use a third party TOTP app or tool to complete the enrolment.

If you have already enrolled but didn't note down the secret it may be possible to find it within your TOTP app (all TOTP apps store the secret in order to generate codes, but not all apps make it visible) - if not, you'll need to reset the MFA on your account and enrol again, noting down the new secret as you do.

Decoding the QR Code

If you cannot find a text version of the secret, just a QR code, you can decode the QR code (turning it into text) using a number of third party tools or apps.  One such option is zbar on the command line for Linux and Mac (or Windows using WSL).

Uzing zbar on the Command Line

zbar tools is in the default Ubuntu repositories.  You can install on Ubuntu directly (or on Windows using WSL) using apt (installing on other distributions may be different):

sudo apt install zbar-tools

Installing on Mac requires Homebrew.  Installing Homebrew is beyond the scope of this article, but if you have it configured you can install zbar as follows:

brew install zbar

To decode a QR code using zbar take a screenshot of the QR code and save it, then pass the path to that image to zbarimg.  For example, if your screenshot is saved as ~/images/my_qr_code.png then the command is:

zbarimg ~/images/my_qr_code.png

This outputs all the information encoded in that QR code as text.  For example:

QR-Code:otpauth://totp/auth:test@example.com?issuer=auth&secret=12341234123412341234f

As you can see, the last part of the string is the secret.

The order is not always the same - some QR codes will return the issuer after the secret.  Be careful when copying the secret, a common error is to accidentally include the &issuer= string along with your secret.