> For the complete documentation index, see [llms.txt](/llms.txt).

# Multi-factor authentication

Embedded Wallets prioritizes security by offering Multi-Factor Authentication (MFA). MFA is an extra layer of protection that verifies a user's identity when accessing their account.

To ensure ownership, the user must provide two or more different backup factors. They have the option to choose from the device, social, backup factor (seed phrase), and password factors to guarantee access to their web3 account. Once a user creates a recovery factor, MFA is enabled, and their keys are divided into three shares for offchain multi-sig, making the key self-custodial.

These backup factors simplify the user experience when recovering their account if they lose access to the original device, or they can sign in on a new device.

note

This is a paid feature and the minimum [pricing plan](https://web3auth.io/pricing.html) to use this SDK in a production environment is the **Scale Plan**. You can use this feature in Web3Auth Sapphire Devnet network for free.

## Enable using the multi-factor authentication level

For a dapp, we provide various options to set up MFA. You can customize the MFA screen by passing the `mfaLevel` parameter in the `connectTo` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level.

Note

If you are using default verifiers, your users may have set up MFA on other dapps that also use default Web3Auth verifiers. In this case, the MFA screen will continue to appear if the user has enabled MFA on other dapps. This is because MFA cannot be turned off once it is enabled.

### Multi-factor authentication level options

| MFA Level | Description                                                  |
| --------- | ------------------------------------------------------------ |
| DEFAULT   | Shows the MFA screen every third sign-in.                    |
| OPTIONAL  | Shows the MFA screen on every sign-in, but user can skip it. |
| MANDATORY | Makes it mandatory to set up MFA after first sign-in.        |
| NONE      | Skips the MFA setup screen.                                  |

### Usage

```kotlin
val loginResponse = web3Auth.connectTo(
  LoginParams(
    AuthConnection.GOOGLE,
    mfaLevel = MFALevel.MANDATORY
  )
)

```

## Explicitly enable multi-factor authentication

The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will used during custom verifiers. If you are using default sign-in providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well.

**Default Verifier**

Usage

```kotlin
import android.widget.Button
import com.web3auth.core.Web3Auth
import android.os.Bundle

class MainActivity : AppCompatActivity() {
    private lateinit var web3Auth: Web3Auth

     private fun enableMFA() {
       val completableFuture = web3Auth.enableMFA()

        completableFuture.whenComplete{_, error ->
            if (error == null) {
                Log.d("MainActivity_Web3Auth", "Launched successfully")
                // Add your logic
            } else {
                // Add your logic on error
                Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong")
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        // Setup UI and event handlers
        val enableMFAButton = findViewById<Button>(R.id.enableMFAButton)
        enableMFAButton.setOnClickListener { enableMFA() }
        ...
    }
    ...
}

```

**Custom JWT Verifier**

Usage

```kotlin
import android.widget.Button
import com.web3auth.core.Web3Auth
import android.os.Bundle

class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Auth

     private fun enableMFA() {
        val loginParams = LoginParams(
            AuthConnection.CUSTOM,
            idToken = "your_jwt_token"
        )

        val completableFuture = web3Auth.enableMFA(loginParams)

        completableFuture.whenComplete{_, error ->
            if (error == null) {
                Log.d("MainActivity_Web3Auth", "Launched successfully")
                // Add your logic
            } else {
                // Add your logic on error
                Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong")
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        // Setup UI and event handlers
        val enableMFAButton = findViewById<Button>(R.id.enableMFAButton)
        enableMFAButton.setOnClickListener { enableMFA() }
        ...
    }
    ...

}


```

## Configure multi-factor authentication settings

You can configure the order of MFA or enable/disable MFA type by passing the `mfaSettings` parameter in `Web3AuthOptions`.

Note

- At least two factors are mandatory when setting up the `MfaSettings`.
- If you set `mandatory: true` for all factors, the user must set up all four factors.
- If you set `mandatory: false` for all factors, the user can skip setting up MFA. But at least two factors are mandatory.
- If you set `mandatory: true` for some factors and `mandatory: false` for others, the user must set up the mandatory factors and can skip the optional factors. But, the user must set up at least two factors.
- The `priority` field is used to set the order of the factors. The factor with the lowest priority will be the first factor to be set up. The factor with the highest priority will be the last factor to be set up.

### Parameters - `MfaSettings`

`MfaSettings` allows you to set the type of the MFA.

**Table**

| Parameter              | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| `deviceShareFactor?`   | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value.        |
| `backUpShareFactor?`   | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value.        |
| `socialBackupFactor?`  | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value.       |
| `passwordFactor?`      | MFA setting for the password factor. It accepts `MfaSetting` as a value.      |
| `passkeysFactor?`      | MFA setting for the passkeys factor. It accepts `MfaSetting` as a value.      |
| `authenticatorFactor?` | MFA setting for the authenticator factor. It accepts `MfaSetting` as a value. |

**Class**

```kotlin
	data class MfaSettings(
		private var deviceShareFactor: MfaSetting? = null,
		private var backUpShareFactor: MfaSetting? = null,
		private var socialBackupFactor: MfaSetting? = null,
		private var passwordFactor: MfaSetting? = null,
		private var passkeysFactor: MfaSetting? = null,
		private var authenticatorFactor: MfaSetting? = null,
	)

```

### Parameters - `MfaSetting` by factor

`MfaSetting` allows you to configure MFA behavior for a particular MFA type.

**Table**

| Parameter    | Description                                                                     |
| ------------ | ------------------------------------------------------------------------------- |
| `enable`     | Enable/Disable MFA. It accepts `Boolean` as a value.                            |
| `priority?`  | Priority of MFA. It accepts `Int` as a value, where valid range is from 1 to 4. |
| `mandatory?` | Mandatory/Optional MFA. It accepts `Boolean` as a value.                        |

**Class**

```kotlin
data class MfaSetting(
	var enable: Boolean,
	var priority: Int?,
	var mandatory: Boolean?
)

```

### Usage

```kotlin
import com.web3auth.core.Web3Auth
import com.web3auth.core.types.Web3AuthOptions
import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork

val web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
    mfaSettings = MfaSettings(
      deviceShareFactor = MfaSetting(true, 1, true),
      socialBackupFactor = MfaSetting(true, 2, true),
      passwordFactor = MfaSetting(true, 3, false),
      backUpShareFactor = MfaSetting(true, 4, false),
      passkeysFactor = MfaSetting(true, 5, true),
      authenticatorFactor = MfaSetting(true, 6, true),
    )
  ),
  this
)

val loginResponse = web3Auth.connectTo(
  LoginParams(
    AuthConnection.GOOGLE,
    mfaLevel = MFALevel.MANDATORY
  )
)

```