Introduction

When your application uses Multi Factor Authentication (MFA), Astra provides a set of built in helper functions to handle dynamic OTP retrieval and injection during login recordings. This guide covers the available functions, how to import them, and how to use them in your custom login scripts.

Prerequisites

Before you begin, ensure you have:

• A login recording exported as a Puppeteer JS file (not JSON)

• Familiarity with basic JavaScript

• MFA configured on your test account (Email based or TOTP)

• A target already set up in your Astra dashboard

For guidance on creating and exporting a login recording, see How to Record a Login Sequence with Chrome DevTools Recorder.

Available Helper Functions

Email OTP Support

Import statement:

const { getVerificationCode } = require('../mfa/email.js');

Function signature:

async function getVerificationCode(
  emailId,
  receivedAfter,
  place = "html",
  verificationCodeRegex = /<span[^>]*>(\d+)<\/span>/
)

Function:

getVerificationCode(emailId, receivedAfter, place, verificationCodeRegex)

Parameters

Accepted values for place:

• html – Search in the HTML content of the email

• text – Search in the plain text content of the email

• codes – Use Astra's built in AI based code detection

Default regex:

/<span[^>]*>(\d+)<\/span>/

Returns

Returns the extracted verification code as a string, or null if no code is found.

Example Usage

await new Promise(resolve => setTimeout(resolve, 10000)); // Wait for email delivery

const verificationCode = await getVerificationCode(
  "testuser@example.com",
  "",
  "html"
);

TOTP Support

Import statement:

const { generateTOTP } = require('../mfa/otp.js');

Function signature:

function generateTOTP(secret, digits = 6, period = 30)

Function:

generateTOTP(secret, digits, period)

Parameters

Returns

Returns the generated TOTP code as a string.

Example Usage

const otp = generateTOTP("YOUR_TOTP_SECRET_HERE");

How to Use These Functions in Your Login Script

Once your login recording is exported as a Puppeteer JS file, locate the section where the OTP is entered and replace the hardcoded value with the appropriate helper function.

Before

await page.type('#otp-input', '123456');

After (Email OTP)

await new Promise(resolve => setTimeout(resolve, 10000));

const verificationCode = await getVerificationCode(
  "testuser@example.com",
  "",
  "html"
);

await page.type('#otp-input', verificationCode);

After (TOTP)

const otp = generateTOTP("YOUR_TOTP_SECRET_HERE");

await page.type('#otp-input', otp);

Expected Outcome

When the login recording runs during a scan, the helper functions dynamically retrieve or generate the correct OTP at runtime. The scanner successfully authenticates into your application and proceeds to scan authenticated areas without requiring manual intervention.

Troubleshooting

getVerificationCode Returns Null

Possible causes:

• The email address does not exactly match the mailbox receiving the OTP

• The OTP email has not yet arrived

• The OTP format does not match the default extraction pattern

Resolution:

• Verify the value supplied in the emailId parameter

• Increase the wait time before calling the function

• Try changing the place parameter from html to text or codes

• Provide a custom verificationCodeRegex that matches your email format

Invalid place Value Error

The place parameter only supports the following values:

• html

• text

• codes

Using any other value may cause the helper function to fail. If you are unsure which option to use, start with html, which is the default behavior.

TOTP Code Is Invalid or Expired

Possible causes:

• The secret is incorrect

• The system clock is out of sync

• Your provider uses a non standard validity period

Resolution:

• Ensure the secret value is the raw TOTP secret from your authenticator setup

• Verify the scanning environment has accurate system time

• Adjust the period parameter if your provider uses a custom validity window

Login Recording Fails After OTP Entry

Possible causes:

• The application requires additional time to complete authentication

• The recording contains unsupported browser events

Resolution:

• Add a short pause after entering the OTP

• Review the login recording for browser internal pages or Meta key events

• Follow the cleanup steps in Fixing Errors When Uploading Puppeteer Login Recording Files

Unsure Which MFA Type Your Application Uses

Email OTP

Your application sends a one time verification code to an email address during login.

TOTP

Your application requires a code generated by an authenticator application such as Google Authenticator or Authy.

Related Tasks

• How to Record a Login Sequence with Chrome DevTools Recorder

• Fixing Errors When Uploading Puppeteer Login Recording Files

• How to Configure Authentication for DAST Scans

• Troubleshooting Login Recording Failures