Multi-factor authentication in React Native SDK

The Multi-Factor Authentication feature lets users create a backup share (recovery phrase), which they use to log in from a new device or recover their account if they lose their device.

note

This is a paid feature and the minimum pricing plan to use this SDK in a production environment is the Scale Plan. You can use this feature in Web3Auth Sapphire Devnet network for free.

MFA level

Pass mfaLevel to connectTo to control when the MFA setup screen appears during sign-in:

MFA_LEVELS value	Behavior
MFA_LEVELS.OPTIONAL	Shows the MFA setup screen on every sign-in; the user can skip it.
MFA_LEVELS.MANDATORY	The user must set up MFA after the first sign-in.
MFA_LEVELS.NONE	Never shows the MFA setup screen.

import { AUTH_CONNECTION, MFA_LEVELS, useWeb3AuthConnect } from '@web3auth/react-native-sdk'
import { Button } from 'react-native'

function MfaLoginView() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const handleLogin = () =>
    connectTo({
      authConnection: AUTH_CONNECTION.GOOGLE,
      mfaLevel: MFA_LEVELS.MANDATORY,
    })

  return <Button title="Sign in" disabled={loading} onPress={handleLogin} />
}

If you don't pass mfaLevel, the sign-in flow uses its default behavior.

caution

If a user has already enabled MFA through another app that uses the same Web3Auth verifier, the MFA screen will continue to appear regardless of the mfaLevel setting. MFA cannot be disabled once it has been enabled by the user.

Runtime MFA management

Use the useEnableMFA and useManageMFA hooks to let users set up or update their MFA factors from within your app:

import { useEnableMFA, useManageMFA } from '@web3auth/react-native-sdk'

function MFAControls() {
  const { enableMFA, loading: enabling } = useEnableMFA()
  const { manageMFA, loading: managing } = useManageMFA()

  return (
    <View>
      <Button title="Enable MFA" disabled={enabling} onPress={() => enableMFA()} />
      <Button title="Manage MFA" disabled={managing} onPress={() => manageMFA()} />
    </View>
  )
}

MFA factor order (Scale plan and above)

note

Configuring mfaSettings is a paid feature. See pricing. You can test it on sapphire_devnet at no cost.

Pass an mfaSettings object in web3AuthOptions to configure which MFA factors are available and in what order they are shown:

import { type MfaSettings, type Web3AuthContextConfig } from '@web3auth/react-native-sdk'

const mfaSettings: MfaSettings = {
  deviceShareFactor: { enable: true, priority: 1, mandatory: true },
  backUpShareFactor: { enable: true, priority: 2, mandatory: true },
  socialBackupFactor: { enable: true, priority: 3, mandatory: false },
  passwordFactor: { enable: true, priority: 4, mandatory: false },
  passkeysFactor: { enable: true, priority: 5, mandatory: false },
  authenticatorFactor: { enable: true, priority: 6, mandatory: false },
}

const web3AuthConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    // ...
    mfaSettings,
  },
}

mfaSettings rules

• At least two factors must be marked mandatory: true.
• The priority field determines the display order (lower = shown first).
• If all factors have mandatory: false, the user can still skip the screen. At least two must be set up overall.

Available MFA factors

Factor key	Description
deviceShareFactor	Device-bound share (default factor)
backUpShareFactor	Downloadable recovery phrase
socialBackupFactor	OAuth-based recovery
passwordFactor	Password-protected recovery share
passkeysFactor	Passkey-based recovery
authenticatorFactor	TOTP authenticator app

Related

• useEnableMFA hook reference
• useManageMFA hook reference