Multi-Factor Authentication (MFA)

The PropelAuth hosted account page has a MFA enrollment UI that your users can use to enroll in MFA, view their backup codes, and disable MFA. You do not have to write any additional code to provide your users with MFA, the hosted pages will take care of everything. MFA in PropelAuth comes with two MFA types - TOTP via an Authenticator App and SMS.

Authenticator App (TOTP) MFA

TOTP is the default MFA type and does not require any setup on your side. Your users can easily set up TOTP MFA by navigating to their hosted account page and clicking on Enable 2FA. Alternatively, see Forcing MFA for All Users and Allow Organizations to Require MFA to require users to setup MFA.

When setting up TOTP MFA, the user will be prompted to scan a QR code and confirm the 6-digit code from their Authenticator App, such as Google Authenticator or Authy.

SMS MFA

PropelAuth also offers SMS MFA as an additional MFA method. While TOTP MFA is completely handled for you by PropelAuth, SMS MFA requires you to bring your own SMS provider, such as Twilio or Mailchimp. Here is a basic look at the SMS MFA flow:

1. A user requests an SMS code.
2. PropelAuth sends you a webhook with the user's phone number and a 6 character code.
3. You use your SMS provider to send an SMS to the provided phone number, including the 6 character code in the SMS body.
4. The user receives the SMS and enters the 6 character code.

Enabling SMS MFA

PropelAuth's SMS MFA support sends you a webhook with the user's phone number and 6-character verification code. You can then send this information along to your SMS provider.

To get started, navigate to the Integrations page in your PropelAuth Dashboard and click on Webhooks. We want to add an endpoint and subscribe it to the user.send_mfa_phone_code event. This event will include the following information:

{
  "event_type": "user.send_mfa_phone_code",
  "mfa_phone_number": "+18005550199",
  "code": "ABC123"
}

Next, configure your backend or automation provider to receive the webhook. Here's some more information on our webhooks integration. Then, send the information along to your SMS provider, such as Twilio or Mailchimp.

The last step is to enable SMS MFA in your app. Navigate to the Signup / Login page in your PropelAuth Dashboard and click Settings. Then, toggle the Allow users to use SMS codes as a 2FA method setting.

Once everything is all setup, your users can start using SMS MFA. Your users can setup SMS MFA in the same way as TOTP MFA - by navigating to their hosted account page and clicking on Enable 2FA. They will then have the option to setup MFA with either an Authenticator App (TOTP) or via SMS.

Forcing MFA for all users

You can force all users to set up MFA by enabling the Require all users to set up 2FA setting in the Signup / Login page of your PropelAuth Dashboard. This will require all users to set up MFA before they can access your app.

Allow Organizations to Require MFA

Instead of requiring MFA globally, you can leave the option up to your users. In the Organization Settings page of your PropelAuth Dashboard, you'll find an option "Allow organizations to require 2FA". If enabled, organizations can enable or disable MFA requirements for their members. Additionally, they can choose to enforce it immediately or in the future, in which case we'll proactively email the organization members that don't have MFA set up yet.

Direct Users to Configure MFA themselves

The last option is to enforce MFA yourself. This can be done on the frontend using any of our full-stack and frontend libraries, such as the UserClass from @propelauth/react.

import { useAuthInfo } from "@propelauth/react";

const { userClass } = useAuthInfo();

if (userClass.hasMfaEnabled) {
    console.log("The user has MFA enabled")
} else {
    alert("Please enable MFA in your account")
}

If the user does not have MFA configured, you can direct them to their Account page to enroll in MFA.