Time-based One Time Passwords (TOTP) within GoScript

Note: 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.

AppCheck has a tool at https://ptst.io/static/otp/totp_calc.html to which you can post a TOTP secret and retrieve an access token (it uses the same algorithm than an authenticator app would, but doesn't store the secret).

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 it's not displayed anywhere then use an MFA app on your phone to scan the QR code, then find the secret in the app.
3. Finish logging in manually, so that when the scanner tries to log in it is not asked to enrol again.
4. In GoScript:
   1. Log in to the point where you're asked for the MFA code.
   2. In JavaScript (within the GoScript):
      1. Send the secret to AppCheck's TOTP tool.
      2. Retrieve the TOTP code.
      3. Save the TOTP code to a window object.
   3. Wait until that window object has been written.
   4. Use the value from that variable in the login form's OTP box.
   5. Finish the sign-in process.

Detailed Guide

A GoScript function, getOTPWithTOTPSecret, to retrieve the TOTP code (steps 4.2.x above) is included in the example at the end of this guide.  You can copy this function in to your own GoScript.

Note: The order of the functions within your script does not matter.  You can paste the getOTPWithTOTPSecret function before or after your auth functions.

The function requires a single argument: the TOTP secret.  Since this is not remembered by the tool, you will need to hard code this into your GoScript.

This GoScript command sends your secret to the getOTPWithTOTPSecret function:

getOTPWithTOTPSecret : [TOTP secret]

The function stores the resulting OTP code as a variable in the window object called otp_code.

To retrive the code for use within your GoScript, first wait for it to be written to the window object:

wait for: js: window.otp_code

Then save it as local GoScript variable:

oneTimePassword := js: window.otp_code

Finally, to use this token in a form on the target login page (where the field in the form is called "otp"):

otp = {oneTimePassword}

Example

A complete example script, where the secret is 12341234123412341234f:

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

  getOTPWithTOTPSecret: 12341234123412341234f
  wait for: js: window.otp_code
  oneTimePassword := js: window.otp_code
  otp = {oneTimePassword}
  click: verify
  wait for: Log out
  
def getOTPWithTOTPSecret totp_secret
  js:
    window.addEventListener("message",function(event){
      if(event.data.token){
        window.otp_code = event.data.token
      }
      if(event.data.ready == "totp"){
        event.source.postMessage(
          {
            "totp_code":"{totp_secret}",
            "algorithm": "SHA1",
            "digits": 6,
            "period": 30
            # Note: In a minority of cases the values of algorithm, digits  
            # and period may need changing to match the target TOTP system.
          }, 
          "*")
      }
    }
    )
    var otp_window=window.open("https://ptst.io/static/otp/totp_calc.html")
  pause: 2

In most cases, the section in bold does not require any changes and can be copied directly into your own GoScript.  You will only need to complete the auth.login function as detailed above, and add auth.confirm and auth.logout functions as described in Authentication GoScripts.

If your TOTP system uses settings different from those in the example function (algorithm, digits and period) then you will need to alter those values in the above code to match those used by your TOTP system.