Enroll In Mfa Component

PropelAuth's Enroll In Mfa Component is to be used when a user needs to enroll in MFA before completing their login flow. It is designed to be used when your user has a Login State of TWO_FACTOR_ENROLLMENT_REQUIRED.

We highly recommend reviewing the Login and Signup Guide if using any of our login or signup components.

Enroll In MFA

Trouble scanning? Switch to a text code

Shadcn Installation

Install this component from our shadcn registry.

npx shadcn@latest add https://components.propelauth.com/r/enroll-in-mfa.json

Reference APIs

These are the APIs that are used by the above component. You can use these APIs directly in your own code.

fetchMfaStatusWithNewSecret

Fetches the current user's MFA status. If they do not have MFA enabled, it will provide you with a QR code to help get your user enrolled.

Success Response

Name
type
Type
string
Description
The type of response depending on if the user has MFA enabled or disabled. Returns either Disabled or Enabled.
Name
mfa_enabled
Type
boolean
Description
Returns true if the current user has MFA enabled. Otherwise, returns false.
Name
backup_codes
Type
string[]
Description
Only returned if mfa_enabled equals true. Returns the current users MFA backup codes.
Name
new_secret
Type
string
Description
Only returned if mfa_enabled equals false.
Name
new_qr
Type
string
Description
Only returned if mfa_enabled equals false. The QR code the current user can scan to enable MFA.
Name
has_password
Type
boolean
Description
If the user has a password configured.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Name
success
Description
Successful request.
Name
emailNotConfirmed
Description
User has not yet confirmed their email address.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

Request

const { fetchMfaStatusWithNewSecret } = useAuthFrontendApis()

const response = await fetchMfaStatusWithNewSecret()
await response.handle({
    success: (data) => {
        if (data.mfa_enabled) {
            console.log('MFA is enabled')
            console.log('Backup codes: ', data.backup_codes)
        } else {
            console.log('MFA is disabled')
            console.log('QR code to enable it: ', data.new_qr)
            console.log('Secret to enable it: ', data.new_secret)
        }
    },
    unexpectedOrUnhandled: (error) => {
        console.error(error)
    },
})

Successful Response

// if MFA disabled
{
    "type": "Disabled",
    "mfa_enabled": false,
    "new_secret": "2CPN3MORX7...",
    "new_qr": "iVBORw0KGgoAAAA...",
    "has_password": true
}
// if MFA enabled
{
    "type": "Enabled",
    "mfa_enabled": true,
    "backup_codes": [
    "6GD3YU5AQE",
    "P5NQ28DWR",
    "ICQ036M4L8"
    ],
    "has_password": true
}

enableMfa

Accepts the code provided by your authenticated user when setting up MFA. To set up MFA, use the QR Code (or secret) provided by fetchMfaStatusWithNewSecret.

Arguments

Name
code *
Type
string
Description
The code generated by your user's authenticator.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Name
success
Description
Successful request.
Name
alreadyEnabled
Description
User has MFA enabled already.
Name
badRequest
Description
Incorrect arguments provided. This is the error you will get if the code is incorrect.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

Request

const { enableMfa } = useAuthFrontendApis()

const response = await enableMfa({ code: '123456' })
await response.handle({
    success: () => {
        console.log('MFA enabled')
    },
    badRequest: (error) => {
        console.log('Bad request error:', error.user_facing_errors.code)
    },
    unexpectedOrUnhandled: () => {
        console.log('An unexpected error occurred')
    },
})

Successful Response

{}