Migrating Users From One MFA Factor to Another

Knowledge Articles
1

Problem statement

A use case may involve migrating users from one form of MFA to another. What is the expected outcome for users attempting to log in with MFA after removing an existing factor (e.g. SMS) and activating another (e.g. TOTP) that they are not enrolled with?

Solution

After removing a factor that users are enrolled with and enabling a new factor, if the Email backup factor is not enabled, users will see the following error:

{
  "type": "f",
  "description": "No confirmed authenticators for the enabled factors",
}

If the Email backup factor is enabled, users will be sent a one-time code in their email that they can use to pass the MFA challenge. These users will not be automatically prompted to enroll in the new factor.

To have these users be prompted to enroll in the new factor, their existing enrollment for the now removed MFA factor must be deleted .

To do this:

  1. Start by getting a list of authentication methods for a user with the GET /api/v2/users/{id}/authentication-methods endpoint.
  2. Then use the id for the enrollment of the removed factor at the DELETE /api/v2/users/{id}/authentication-methods/{authentication_method_id} endpoint to delete the enrollment.

On the next login attempt by the user, they will be prompted to enroll in the new MFA factor.