Multi-factor authentication in iOS SDK

Multi-Factor Authentication (MFA) adds an extra layer of protection that verifies your identity when accessing your account. To ensure ownership, you must provide two or more different backup factors. Choose from device, social, backup factor (seed phrase), and password factors to secure access to your web3 account. Once you create a recovery factor, MFA is enabled, and your keys are divided into three shares for offchain multi-sig, making the key self-custodial. With backup factors, you can recover your account if you lose access to your original device or need to sign in on a new 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.

Enable using the MFA level

Customize the MFA screen by passing the mfaLevel parameter in the connectTo method. Three MFA level values are available. If you don't pass mfaLevel, the sign-in flow uses the default behavior of the authentication service.

Note

If you're using default auth connections, your users may have set up MFA on other dapps that also use default Embedded Wallets auth connections. In this case, the MFA screen continues to appear if the user has enabled MFA on other dapps. MFA can't be turned off once enabled.

MFA level options

MFA Level	Description
.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.

public enum MFALevel: String, Codable, Sendable {
    case OPTIONAL = "optional"
    case MANDATORY = "mandatory"
    case NONE = "none"
}

note

MFALevel.DEFAULT was removed in v13. Omit mfaLevel to get the default behavior.

Usage

import Web3Auth

let web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        redirectUrl: "com.yourapp.bundleid://auth",
        web3AuthNetwork: .SAPPHIRE_MAINNET
    )
)

let result = try await web3Auth.connectTo(
    loginParams: LoginParams(
        authConnection: .GOOGLE,
        mfaLevel: .MANDATORY
    )
)

Explicitly enable MFA

The enableMFA method triggers the MFA setup flow for a signed-in user. The SDK reuses the user's current auth connection, so you don't need to pass LoginParams for default sign-in providers. For custom auth connections that need extra sign-in options (such as Auth0), pass a LoginParams object with the same extraLoginOptions you used to sign in.

warning

Users who signed in with an idToken (single-factor authentication) can't enable MFA. enableMFA throws Web3AuthError.enabledMfaNotAllowed for these users.

Default Auth Connection

do {
  let isMFAEnabled = try await web3Auth.enableMFA()
} catch {
  print(error.localizedDescription)
  // Handle Error
}

Custom Auth Connection

do {
    let loginParams = LoginParams(
        authConnection: .CUSTOM,
        extraLoginOptions: ExtraLoginOptions(
            domain: "https://username.us.auth0.com", // Domain of your Auth0 app
            userIdField: "sub"
        )
    )

    let isMFAEnabled = try await web3Auth.enableMFA(loginParams)
} catch {
    print(error.localizedDescription)
    // Handle Error
}

Configure Multi-Factor Authentication settings

Configure the order of MFA or enable/disable MFA types by passing the mfaSettings object in Web3AuthOptions. The SDK merges mfaSettings with the MFA settings configured in your dashboard. For each factor that the dashboard configures, the dashboard setting takes precedence.

Note

• At least two factors are mandatory when setting up mfaSettings.
• If you set mandatory: true for all factors, the user must set up all factors.
• If you set mandatory: false for all factors, the user can skip MFA setup, but at least two factors are still 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 ones, but must set up at least two factors total.
• The priority field sets the order of the factors. The lowest priority value is set up first; the highest is set up last.

MfaSettings parameters

MfaSettings configures which MFA factor types are available.

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 passwordFactor. It accepts MfaSetting as a value.
passkeysFactor?	MFA setting for passkeysFactor. It accepts MfaSetting as a value.
authenticatorFactor?	MFA setting for authenticatorFactor. It accepts MfaSetting as a value.

Class

public struct MfaSettings: Codable {
    public init(
        deviceShareFactor: MfaSetting? = nil,
        backUpShareFactor: MfaSetting? = nil,
        socialBackupFactor: MfaSetting? = nil,
        passwordFactor: MfaSetting? = nil,
        passkeysFactor: MfaSetting? = nil,
        authenticatorFactor: MfaSetting? = nil
    )

    let deviceShareFactor: MfaSetting?
    let backUpShareFactor: MfaSetting?
    let socialBackupFactor: MfaSetting?
    let passwordFactor: MfaSetting?
    let passkeysFactor: MfaSetting?
    let authenticatorFactor: MfaSetting?
}

MfaSetting parameters

MfaSetting configures the behavior of an individual MFA factor.

Table

Parameter	Description
enable	Enable/Disable MFA. It accepts Bool as a value.
priority?	Priority of MFA. Factors with lower values are set up first. It accepts Int as a value.
mandatory?	Mandatory/Optional MFA. It accepts Bool as a value.

Class

public struct MfaSetting: Codable {
    public init(enable: Bool, priority: Int?, mandatory: Bool? = nil) {
        self.enable = enable
        self.priority = priority
        self.mandatory = mandatory
    }

    let enable: Bool
    let priority: Int?
    let mandatory: Bool?
}

Usage

import Web3Auth

let web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        redirectUrl: "com.yourapp.bundleid://auth",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        mfaSettings: MfaSettings(
            deviceShareFactor: MfaSetting(enable: true, priority: 1),
            backUpShareFactor: MfaSetting(enable: true, priority: 2),
            socialBackupFactor: MfaSetting(enable: true, priority: 3),
            passwordFactor: MfaSetting(enable: true, priority: 4),
            passkeysFactor: MfaSetting(enable: true, priority: 5),
            authenticatorFactor: MfaSetting(enable: true, priority: 6)
        )
    )
)

let result = try await web3Auth.connectTo(
    loginParams: LoginParams(
        authConnection: .GOOGLE,
        mfaLevel: .MANDATORY
    )
)