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.

Default MFA level

Set mfaLevel in web3AuthOptions to control when the MFA setup prompt is shown globally:

web3authConfig.ts

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

const web3AuthConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'yourapp://auth',
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    chains: [...],
    mfaLevel: MFA_LEVELS.DEFAULT,
  },
}

MFA_LEVELS value	Behavior
MFA_LEVELS.DEFAULT	Shows the MFA screen on every third login.
MFA_LEVELS.OPTIONAL	Shows the MFA screen on every login, but the user can skip it.
MFA_LEVELS.MANDATORY	MFA setup is required immediately after the first login.
MFA_LEVELS.NONE	MFA setup screen is never shown.

You can also override mfaLevel on a per-login basis by passing it to connectTo:

const { connectTo } = useWeb3AuthConnect()

await connectTo({
  authConnection: AUTH_CONNECTION.GOOGLE,
  mfaLevel: MFA_LEVELS.MANDATORY,
})

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 for free.

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

import { type MfaSettings } 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: {
    ...
    mfaLevel: MFA_LEVELS.MANDATORY,
    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