Customize Adaptive MFA with Rules

You can use Auth0 Rules to create Adaptive MFA flows for a variety of different scenarios. First, determine the desired behavior:

• At what confidence level do you want to trigger MFA?

• How do you want to measure risk? Do you want Auth0 to measure confidence or do you want a custom measurement?

• How do you want to deal with users who are not enrolled in MFA and go through this flow?

You can use rules to cover a number of different risk assessment scenarios.

Adaptive MFA custom rules are only recommended in scenarios where end users are enrolled in MFA. If a user is not enrolled in MFA and your rule assesses a high risk, you will have very limited options to stop a bad actor. If the end-users are not enrolled in MFA, we recommend using the default policy that ships with adaptive MFA, which will take care of adding extra security for this use case.

If you want to implement your own confidence measure using assessors, use Auth0 rules to build business logic to assess risk, present or bypass MFA challenges, and either require or bypass MFA enrollment (using a collection of additional factors).

The following table shows the outcomes based on the result of both the rule and the Adaptive MFA action. If your tenant has the confidence score in the rules, then the Adaptive MFA prompt will be triggered when a confidence score is low.

Auth0 provides two Adaptive MFA rule templates for you to customize: Adaptive MFA and Require MFA Enrollment.

This rule template provides an example and starting point for how to build a custom business rule using individual risk assessments.

First, the rule establishes how the confidence assessments can be read and arranged in a business rule:

const riskAssessment = context.riskAssessment;

  // Example condition: prompt MFA only based on the NewDevice 
  // confidence level, this will prompt for MFA when a user is logging in 
  // from an unknown device.
  let shouldPromptMfa;
  switch (riskAssessment.assessments.NewDevice.confidence) {
    case 'low':
    case 'medium':
      shouldPromptMfa = true;
      break;
    case 'high':
      shouldPromptMfa = false;
      break;
    case 'neutral':
      // When this assessor has no useful information about the confidence, 
      // do not prompt MFA.
      shouldPromptMfa = false;
      break;
  }

Next, the code checks if the user is enrolled in MFA using user.multifactor; if the user is enrolled in MFA, then trigger the MFA challenge.

// It only makes sense to prompt for MFA when the user has at least one 
  // enrolled MFA factor.
  const userEnrolledFactors = user.multifactor || [];
  const canPromptMfa = userEnrolledFactors.length > 0;

  if (shouldPromptMfa && canPromptMfa) {
    context.multifactor = {
      provider: 'any',
      // ensure that we will prompt MFA, even if the end-user has selected to 
      // remember the browser.
      allowRememberBrowser: false
    };
  }
  callback(null, user, context);
}

This rule template provides a way to enforce MFA enrollment (in an adaptive or standard MFA setting). This rule allows you to address scenarios where, upon risky logins, an end-user is forced to enroll in MFA for security purposes. The rule uses user.multifactor to check if a user is enrolled in MFA and if not, trigger enrollment.

function requireMfaEnrollment(user, context, callback) {

  const enrolledFactors = user.multifactor || [];
  if (enrolledFactors.length === 0) {
    // The user has not enrolled in any MFA factor yet, trigger an MFA enrollment
    context.multifactor = {
      provider: 'any'
    };
  }
  callback(null, user, context);
}

If no action is taken by rules, the outcome defaults to Adaptive MFA. However, in the event you want to use a particular accessor, you can use rules to skip the Adaptive MFA outcome. Apply none to context.multifactor.provider.

} else {
  console.log('SKIP MFA');
  context.multifactor = {
    provider: 'none'
  };
}

Auth0 analyzes how the severity and the interactions between individual assessments predict anomalous behavior, and then assigns an overall risk or confidence score. Low confidence means that the login does not match the patterns previously displayed by the user. The following assessors are computed and available for rules. Confidence assessments are available for use in rules using the context.riskAssessment object.

The confidence scores are exposed within the riskAssessment context object. Here is the structure of the object accessible in the context of a rule:

context.riskAssessment = {
  confidence: 'low' | 'medium' | 'high' | 'neutral',
  version: '1',
  assessments: {
    UntrustedIP: {
      confidence: 'low' | 'medium' | 'high' | 'neutral',
      code: 'not_found_on_deny_list' | 'found_on_deny_list',
      details: { // only if 'found_on_deny_list'
        ip: '192.168.1.1',
        matches: '192.168.0/64',
        source: 'firehol'
      }
    },
    NewDevice: {
      confidence: 'low' | 'medium' | 'high' | 'neutral',
      code: 'match' | 'partial_match' | 'no_match',
      details: {
        device: 'known' | 'unknown',
        useragent: 'known' | 'unknown',
      }
    },
    ImpossibleTravel: {
      confidence: 'low' | 'medium' | 'high' | 'neutral',
      code: 'missing_geoip', | 'anonymous_proxy' | 'unknown_location' | 'initial_login' | 'location_history_not_found' | 'invalid_travel' | 'minimal_travel_from_last_login' | 'impossible_travel_from_last_login' | 'substantial_travel_from_last_login' | 'travel_from_last_login'
    } 
  }
};

Here are some suggestions for how to build custom rules based on your use case.

• Context Object Properties in Rules
• Enable Adaptive MFA
• Adaptive MFA Log Events