How to Trigger a Custom MFA Page with a Post-Login Action

Knowledge Articles
1

Overview

This article is for tenant admins who want to trigger the customized Multifactor Authentication (MFA) page within a Post-Login Action.

Applies To

  • Actions
  • Custom Multifactor Authentication (MFA) Page
  • Multifactor Authentication (MFA)
  • Classic Login

Solution

Use the method enable since challengeWith or challengeWithAny only works with Universal Login. If the user uses a custom MFA page, it means the Classic Login Experience will be used, so the client has to use API.multifactor.enable. See Actions Triggers: post-login - API Object for more details.

To trigger a custom MFA Page within actions, follow these steps:

  1. Go to Management Dashboard > Security > Multi-Factor Auth
  2. Enable the factors (at least one factor has to be enabled)
  3. In the Define Policies section, set the Require Multi-Factor Auth to Never and click Save
  4. In the Additional Settings section, enable the option to Customize MFA Factors using Actions
  5. Within Branding > Advanced Options, customize the Multi-Factor Authentication page. See the following HTML code for testing:
<!DOCTYPE html>
<html>
<head>
  <title> MY CUSTOM MFA</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <style type="text/css">

    html, body { padding: 0; margin: 0; background-color:#52AA8A }

    .table {
      display: table;
      position: absolute;
      height: 100%;
      width: 100%;
      background-color: "#33"
    }

    .cell {
      display: table-cell;
      vertical-align: middle;
    }

    .content {
      padding: 25px 0px 25px 0px;
      margin-left: auto;
      margin-right: auto;
      width: 280px; /* login widget width */
    }

  </style>
</head>

<body>

  <div class="table">
    <div class="cell">
      <div class="content">
        <span> VPTEST VPTEST  VPTEST VPTEST </span>
        <p>VPTEST</p>
        <!-- WIDGET -->
        <div class="js-mfa-container mfa-container" id="container"></div>
      </div>
    </div>
  </div>

  <script src="//cdn.auth0.com/js/mfa-widget/mfa-widget-1.8.min.js"></script>

  <script>
    (function() {
      return new Auth0MFAWidget({
        container: "container",

        theme: {
          icon: "{{ iconUrl | escape | default: '//cdn.auth0.com/styleguide/1.0.0/img/badge.png' }}",
          primaryColor: "{{ primaryColor | escape | default: '#ea5323' }}"
        },

        requesterErrors: [
          {% for error in errors %}
            { message: "{{ error.message | escape }}", errorCode: "{{ error.code | escape }}" }
          {% endfor %}
        ],

        mfaServerUrl: "{{ mfaServerUrl | escape }}",
        {% if ticket %}
        ticket: "{{ ticket | escape }}",
        {% else %}
        requestToken: "{{ requestToken | escape }}",
        {% endif %}
        postActionURL: "{{ postActionURL | escape }}",

        userData: {
          userId: "{{ userData.userId | escape }}",
          email: "{{ userData.email | escape }}",
          friendlyUserId: "{{ userData.friendlyUserId | escape }}",
          tenant: "{{ userData.tenant | escape }}",
          {% if userData.tenantFriendlyName %}
          tenantFriendlyName: "{{ userData.tenantFriendlyName | escape }}"
          {% endif %}
        },
        globalTrackingId: "{{ globalTrackingId | escape }}",
        {% if allowRememberBrowser %}allowRememberBrowser: {{ allowRememberBrowser | escape }}, {% endif %}
        {% if stateCheckingMechanism %}stateCheckingMechanism: "{{ stateCheckingMechanism | escape }}", {% endif %}
      });
    })();
  </script>
</body>
</html>
  1. Go to Actions > Triggers > post-login and create an Action to trigger the MFA using api.multifactor.enable. Use this example for testing:
exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('any',{allowRememberBrowser: true});
};

Now, after the log-in event, the end-user will be challenged to enroll (if not already) or pass the MFA, but within the Classical Customized Universal Login Page.