MFA TOTP Devices

MailSlurp offers free virtual multi-factor authentication devices. These are similar to Google Authenticator or Duo but can be created on-demand via API call or within the hosted UI interface. Virtual TOTP devices are invaluable for testing, automation, and IT workflows involving secure systems and two factor authentication.

For API reference see the MFA Controller endpoints.

Features

With MailSlurp MFA controller you can:

• Create unlimited virtual TOTP devices on demand
• Associate devices with users and issuing apps
• Generate time-based one-time passwords in code, tests, and dashboards

Examples

The best way to learn about TOTP is to see our example projects and tutorials:

• TOTP testing tutorial blog post
• Selenium Java Auth0 MFA/TOTP Github example

How it works

Terminology

TOTP MFA can be complex. Here are some key terms:

Term	Description
OTP Auth URL	A special URL containing the secret for connecting an Authenticator. Usually in the form of a QR code.
TOTP	Time-based One-Time Password. A temporary code generated using a shared key.
MFA	Multi-Factor Authentication. Security using more than one verification method.
Secret Key	A base32-encoded string shared between client and server to generate TOTPs.
OTP	One-Time Password. A code valid for a single authentication session.
QR Code	Encoded image containing the TOTP secret for easy setup in authenticator apps.
Authenticator	App or device that generates TOTP codes (e.g., MailSlurp).

Extract the secret for connection

To create a TOTP device the IDP must present to you either:

• A QR code
• OR a base32-encoded secret
• OR a special otpauth:// URL

This pairing stage is crucial for creating a valid TOTP device. You must submit the values during creation.

Creating TOTP devices via URL

Usually the QR code has a data attribute in the DOM containing the otpauth:// style url. You can submit this to MailSlurp to link a new device:

// next create a TOTP authenticator device in MailSlurp
var mfaController = new MfaControllerApi(apiClient);
var virtualTotpDevice = mfaController.createTotpDeviceForOtpAuthUrl(new CreateTotpDeviceOtpAuthUrlOptions()
        // pass the QR code otpauth:// URI to MailSlurp
        .otpAuthUrl(optAuthUrl)
).execute();

Note: these examples use Java but MailSlurp is available in a wide range of language.

Other methods are available. You can either:

• Pass src of the QR img to MailSlurp for fetching.
• Click option options in the IDP to view the base32-encoded secret string. Submit this to MailSlurp
• Use the test framework to screenshot the QR code and then submit it to MailSlurp for decoding.

See the MFA controller for more information.

Generate one-time passwords

You can generate a valid OTP code like so:

// now generate a secret code from the TOTP device and submit it
var oneTimeCode = mfaController.getTotpDeviceCode(virtualTotpDevice.getId())
        // ensure code is valid long enough to be entered by selenium
        .minSecondsUntilExpire(10)
        .execute().getCode();
wait.until(visibilityOfElementLocated(By.id("code"))).sendKeys(oneTimeCode);

// submit the code
wait.until(elementToBeClickable(By.cssSelector("button[data-action-button-primary=\"true\"]"))).click();

wait.until(elementToBeClickable(By.cssSelector("button[name='action'][value='accept']"))).click();

Testing sequence

When writing QA and testing automations using virtual TOTP devices follow this logic: