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.

Some login processes involve the use of email for receiving either One Time Passwords (OTPs) or single-use URLs ("Magic Links").  This can be achieved in GoScript by using an email address controlled by AppCheck ([anything]@ptst.io) which the GoScript system can access.

AppCheck provides a system for returning the body of the last emailed received at a given @ptst.io email addresses:

https://ptst.io/latest_email_by_to?to=[email address]

You can generate a unique email address using https://ptst.io/generate_random_account.

For example, the generator has been used to create the address 378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.  The body of the latest email sent to this address can be seen at https://ptst.io/latest_email_by_to?to=378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.

If you are setting up multiple scans that will run concurrently against the same authentication system then it would be best to use a unique email address for each scan to avoid conflicts.  See Selecting an Account for your Authenticated Web Application Scan.

Using a pre-written GoScript function (which uses JavaScript to perform an HTTP GET request) we can retrieve a value from an email within a GoScript.  If we arrange for the OTP or Magic Link to be sent to that address we can therefore retrieve the email, extract the value and use it within the script.

• Overview
• Detailed Guide
• Examples

Overview

The process for setting up an authentication GoScript using email-based OTP or Magic Links is as follows:

1. Register a new, unique email address using the generator at https://ptst.io/generate_random_account.
2. Use this email address to register an account with the target application.
3. In GoScript:
   1. Use the chosen email address to log in, triggering the target application's MFA system so that it emails that address.
   2. Wait for the email to come through.
   3. Use the pre-written GoScript function from this guide, which uses JavaScript to:
      
      1. Retrieve the contents of the email from https://ptst.io/latest_email_by_to?to=[email address].
      2. Extract the OTP code or Magic Link.  The pattern required to extract it will vary between MFA systems, but an example can be seen in the scripts below.
      3. Save the OTP code or Magic Link to a window object.
   4. Wait until that window object has been written.
   5. Use the value from that variable in the login form's OTP box, or use a go: command to visit the URL of the Magic Link.
   6. Finish the sign-in process.

Detailed Guide

A GoScript function, getValueFromEmail, to retrieve the OTP code or Magic Link (step 3.c above) is included in the examples at the end of this guide.  You can copy this function directly in to your own GoScript.

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

You will need a pause between logging in and getting the token from the email. If you do this too quickly you might end up taking the token from the previous email, for example pause: 10 to allow ten seconds for the email to be delivered.

The function requires two arguments.  The first is the email address being used; the second is a regular expression which extracts the OTP code or Magic Link from the body of the email.  This regular expression will need to be written specifically for the particular MFA system being used.

This GoScript command sends your email address and Regular Expression to the getValueFromEmail function:

getValueFromEmail: [email address] /[regular expression]/

For example, using the email address generated above, and a simple Regular Expression (looking for a code), we would call the getValueFromEmail function like this:

getValueFromEmail: 378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io /code\sis:\s([0-9\s]+)\n/

This Regular Expression looks for the string "code is: " followed by a series of numbers and white-space, followed by a newline character.  The numbers and white-space are in a pair of brackets () and so they form the first Regular Expression capture group.  The contents of the capture group, not the whole matched string, are extracted and used as the OTP code.

The / characters at the start and end of the Regular Expression are not part of the Expression; they indicate to the system that the value between them is a Regular Expression.

Since the arguments are separated by spaces, they cannot include spaces within them, which is why in this example I've used \s in the Regular Expression.

The function stores the resulting OTP or Magic Link as a variable in the window object called extracted_value.

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

wait for: js: window.extracted_value

Then save it as local GoScript variable, in this example we call it extractedValue:

extractedValue := js: window.extracted_value 

Finally, to use the extracted value as an OTP in a form on the target login page (where the field in the form is called "otp"):

otp = {extractedValue}

or to visit the URL of the Magic Link:

go: {extractedValue}

Examples

The sections in bold do 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.

One Time Password

A complete example script, using the email address stored in the {username} variable, and the Regular Expression described above, to extract an OTP and use it in the login process.

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: You will shortly receive a verification code via email

  pause: 10

  getValueFromEmail: {username} /code\sis:\s([0-9\s]+)\n/
  wait for: js: window.extracted_value
  extractedValue := js: window.extracted_value

  otp = {extractedValue}
  press: Enter
  wait for: Log out

def getValueFromEmail emailAddress pattern
  js: 
    var request = new XMLHttpRequest;
    request.open("GET", "https://ptst.io/latest_email_by_to?to={emailAddress}", true);
    request.onreadystatechange = function() {
      if (this.readyState == 4 && this.status == 200) {
        var match = this.responseText.match({pattern});
        if (match) {
          window.extracted_value = String(match[1]).replace(/\s+/g, '');
        }
      }
    }
    request.send();

Magic Link

A complete example script, using the email address stored in the {username} variable and a Regular Expression to extract a Magic Link and follow it.

The Regular Expression used here finds the value of the first href value within the email body.  You may need a more complex Expression if your emails contain multiple links.

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: You will shortly receive a verification code via email

  pause: 10

  getValueFromEmail: {username} /href=\"(.*?)\"/
  wait for: js: window.extracted_value
  extractedValue := js: window.extracted_value

  otp = {extractedValue}
  press: Enter
  wait for: Log out

def getValueFromEmail emailAddress pattern
  js: 
    var request = new XMLHttpRequest;
    request.open("GET", "https://ptst.io/latest_email_by_to?to={emailAddress}", true);
    request.onreadystatechange = function() {
      if (this.readyState == 4 && this.status == 200) {
        var match = this.responseText.match({pattern});
        if (match) {
          window.extracted_value = String(match[1]).replace(/\s+/g, '');
        }
      }
    }
    request.send();