# 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](/docs/swagger/) 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](https://www.mailslurp.com/examples/selenium-auth0-mfa-login-test-totp-api/)
- [Selenium Java Auth0 MFA/TOTP Github example](https://github.com/mailslurp/examples/tree/master/totp-mfa-auth0-selenium)

## 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:

```java
// 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](/docs/sdks/).

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](/docs/api/) for more information.

### Generate one-time passwords

You can generate a valid OTP code like so:

```java
// 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:

![](/mermaid-gen/plus-address.mmd.svg)