Now that we’ve seen how the MFA APIs work, you may want to consider how you want to present the MFA enrollment experience to your users. This guide will cover some of the considerations you should take into account when designing your enrollment experience.

The MFA APIs support multiple methods of authentication. Consider providing your users with multiple options for enrolling in MFA. Adding flexibility will reduce friction in users adoption.

If a user has enrolled in multiple methods, consider letting them select a primary. This will allow you to challenge them with the method they are most comfortable, whilst still benefiting from the security of a backup in case they lose access.

As we have previously seen, when enrolling a totp factor using the MFA API, the response returns a qr_code and a secret.

The qr_code value can be passed directly to the source on an image tag as follows:

<img
  src={factor.qr_code}
  with="100"
  height="100"
  alt="Scan this QR code to enroll"
/>;

However, some users may not be able to scan the QR code. Consider providing the secret value in the UI as an alternate way to set up their authenticator app.

Scan the QR code with the app

Alternatively, enter the following secret: O5KQ23S3FICSYHSRGJRAWVJVKVYUSYLB

Additionally, consider describing the QR code for assistive technologies:

<>
  <img
    src={factor.qr_code}
    with="100"
    height="100"
    alt="Scan this QR code to enroll"
    aria-describedby="secret-note"
  />

  <p
    id="secret-note"
  >
    Alternatively, enter the following secret: {factor.secret}
  </p>
</>;

In order to make the experience as smooth as possible for your users, there are a few things to consider regarding the input they will use to fill in their one-time-passcode.

You may be tempted to use a number input as it will show the mobile keyboard for numbers only. This is not recommended because a browser expects a number input to be countable, rather than a sequence of multiple numbers, which can cause unexpected behavior.

Instead, we recommend using a text input (type="text") with the inputmode="numeric" attribute to provide mobile devices with the expected numerical keyboard prompt.

Setting autocomplete="one-time-code" will enable autofill with in any user-agent that supports it. This will for example ensure Safari on iOS/MacOS can suggest/auto-fill the one-time-code received via SMS.

Consider also submitting the form automatically as soon as the passcode length has been met. This should help reduce the friction of using two-factor authentication for your users.

Consider using client-side validation to ensure the user enters a valid one-time-passcode. This will reduce the number of requests to the server and improve the user experience.

pattern="^\d{6}$" can be used to validate the length of the one-time-passcode.

Here is a code example implementing the above considerations:

<>
  <label htmlFor="code">One-time-code</label>
  <input
    id="code"
    name="code"
    type="text"
    inputMode="numeric"
    autoComplete="one-time-code"
    required
    pattern="^\d{6}$"
  />
</>;

The following interactive example shows a full UI for enrolling in MFA, and encompasses all of the considerations mentioned above.