Import User MFA Authenticator Enrollments

You can import a user's MFA enrollments with automatic migration and bulk user imports. The supported enrollment types are:

  • Email: for email verification.

  • Phone: for SMS verification.

  • OTP: for One-Time Passwords (OTPs) used with authenticator applications, such as Google Authenticator.

Importing MFA enrollments provides a seamless user experience, since users won't have to re-enroll after migration.

The classic login experience does not support factor selection for users with multiple factors. If you plan to import users with multiple registered factors, consider using the Universal Login experience.

Schema

The schema applies to MFA factors for both of the following workflows.

{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "totp": {
                "type": "object",
                "properties": {
                "secret": {
                    "type": "string",
                        "pattern": "^[A-Z2-7]+$",
                        "description": "The OTP secret is used for MFA authentication with Google Authenticator type apps. It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
                    },
                },
                "additionalProperties": false,
                "required": ["secret"],
            },
            "phone": {
                "type": "object",
                "properties": {
                "value": {
                    "type": "string",
                    "pattern": "^\\+[0-9]{1,15}$",
                    "description": "The phone number for SMS or Voice MFA. The phone number should include a country code and begin with +, such as: +12125550001"
                },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
            "email": {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "string",
                        "format": "email",
                        "description": "The email address for MFA"
                    },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
        },
        "maxProperties": 1,
        "additionalProperties": false,
    },
    "minItems": 1,
    "maxItems": 10
}

Was this helpful?

/

Automatic migration

MFA enrollments can also be imported during an automatic migration. This can be accomplished by providing any existing enrollments in the mfa_factors field of the user that is provided to the callback at the end of your custom DB login script.

Any failures will appear in your tenant logs as failed logins, and will be distinguishable from other failures by their description: Unable to import MFA factors. For example: 

{
  "_id": "5e9df3b29ebabe00571c04a7",
  "date": "2020-04-20T19:10:42.916Z",
  "type": "fu",
  "description": "Unable to import MFA factors.",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_mMkvaycgzgCS0p0z",
  "client_id": "aCbTAJNi5HbsjPJtRpSP6BIoLPOrSj2Cgg",
  "client_name": "All Applications",
  "ip": "10.12.13.1",
  "client_ip": null,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
  "details": {
    "error": {
      "message": "Unable to import MFA factors."
    }
  },
  "user_name": "test@test.io",
  "strategy": "auth0",
  "strategy_type": "database"
}

Was this helpful?

/

Bulk user import

  1. Prepare a users.json file. See bulk user imports for details.

  2. Include existing MFA enrollments for each user.

  3. Start a bulk user import.

  4. Update the factors of any existing users by enabling the upsert option in your initial request.

  5. Once the import job completes, check the response for any errors. If any of the users' MFA factors failed to import, you will see errors such as:

When using the upsert option, any non-MFA related updates to existing users will have been applied to the user's profile. For example, the following error summary shows the user's picture attribute was successfully set to http://example.org/jdoe.png, however we were unable to import the provided MFA factors. In cases like this, it is safe to retry the import for failed users.

[
  {
    "user": {
      "email": "antoinette@contoso.com",
      "picture": "http://example.org/jdoe.png",
      "mfa_factors": [
        {
          "totp": {
            "secret": "2PRXZWZAYYDAWCD"
          }
        },
        {
          "phone": {
            "value": "+15551112233"
          }
        },
        {
          "email": {
            "value": "antoinette@antoinette.biz"
          }
        }
      ]
    },
    "errors": [
      {
        "code": "MFA_FACTORS_FAILED",
        "message": "Unable to import factors"
      }
    ]
  }
]

Was this helpful?

/

Recovery codes

Auth0 does not provide a way to import recovery codes. When the user's MFA factors are imported, they won't have a recovery code.

To provide users a recovery code, you can check if they have one enrolled, and if not, use the Recovery Code Regeneration endpoint to generate a new one.

Learn more