Skip to main content

Multi Factor Authentication with PnP Web Modal SDK

At Web3Auth, we prioritize your security by offering Multi-Factor Authentication (MFA). MFA is 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. You have the option to choose from the device, social, backup factor (seed phrase), and password factors to guarantee access to your Web3 account. Once you create a recovery factor, MFA is enabled, and your keys are divided into three shares for off-chain multi-sig, making the key self-custodial. With backup factors, you can easily recover your account if you lose access to your original device or helps login into a new device.

For a dApp, we provide various options to set up Multi-Factor Authentication. You can customize the MFA screen by setting the mfaLevel argument. You can enable or disable a backup factor and change their order. Currently, there are four values for mfaLevel:

  • default: presents the MFA screen every third login
  • optional: presents the MFA screen on every login, but you can skip it
  • mandatory: make it mandatory to set up MFA after login
  • none: skips the MFA setup screen
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.

Installing Auth Adapter​

Social logins in Web3Auth are enabled by the auth-adapter. Natively, it is already present and preconfigured within the Plug and Play SDK, but for custom configurations, you need to install the adapter package.

npm install --save @web3auth/auth-adapter

Configuring Auth Adapter​

While instantiating the Auth Adapter, you can pass some configuration objects to the constructor. One of these configurations is the loginSettings configuration which enables you to make changes in the adapter, enabling add more settings to your login function using web3auth.

tip

Checkout the auth-adapter SDK Reference for more details on different configurations you can pass for customisations.

Login Settings​

loginSettings​

VariableDescription
loginProviderSets the OAuth login method to be used. You can use any of the valid loginProvider from the supported list.

The list of available options: google, facebook, reddit, discord, twitch, apple, line, github, kakao, linkedin, twitter, weibo, wechat, email_passwordless, sms_passwordless, jwt
mfaLevel?You can set the mfaLevel to customize when mfa screen should be shown to user. It currently accepts 4 values:
  • 'default' Setting mfa level to default will present mfa screen to user on every third login.
  • 'optional' Setting mfa level to default will present mfa screen to user on every login but user can skip it.
  • 'mandatory' Setting mfa level to mandatory will make it mandatory for user to setup mfa after login.
  • 'none' Setting mfa level to none will make the user skip the mfa setup screen
extraLoginOptions?This can be used to pass standard oauth login options to loginProvider. For ex: you will have to pass login_hint as user's email or phone number and domain as your app domain in extraLoginOptions while using email_passwordless or sms_passwordless loginProvider. It accepts ExtraLoginOptions as a value.
dappShare?Custom logins can get a dApp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to login seamlessly. dappShare is a 24 word seed phrase. It accepts string as a value.
curve?This curve will be used to determine the public key encoded in the jwt token which returned in getUserInfo function after user login. You can use that public key from jwt token as a unique user identifier in your backend.
  • 'secp256k1': secp256k1 based pub key is added as a wallet public key in jwt token to use.
  • 'ed25519': ed25519 based pub key is added as a wallet public key in jwt token to use.
Note: This parameter won't change format of private key returned by auth. Private key returned by auth is always secp256k1. It accepts SUPPORTED_KEY_CURVES_TYPE as a value.
appState?Any custom state you wish to pass along. This will be returned to you post redirect. Use this to store data that you want to be available to the dApp after login. It accepts string as a value.
redirectUrl?App's URL where user will be redirected after login. Register this URL in the developer dashboard, else initialization will give error. It accepts string as a value.
Usage
import { AuthAdapter } from "@web3auth/auth-adapter";

const authAdapter = new AuthAdapter({
  loginSettings: {
    mfaLevel: "mandatory", // default, optional, mandatory, none
  },
});

Adapter Settings​

adapterSettings​

VariableDescription
clientIdThe unique identifier for your application. Obtain this by registering your dapp in the Web3Auth Dashboard
networkThe Web3Auth network to be used.
buildEnvThis parameter will be used to change the build environment of auth sdk, mainly for testing purposes. default is production.
redirectUrlThe URL where users will be redirected after login.
uxModeTwo uxModes supported are:- 'popup': In this uxMode, a popup will be shown to user for login. Use 'redirect': In this uxMode, user will be redirected to a new window tab for login. Use of 'redirect' mode is recommended in browsers where popups might get blocked.
replaceUrlOnRedirectreplaceUrlOnRedirect removes the params from the redirected url after login
originDataoriginData is used to verify the origin of dapp by iframe. You don't have to pass originData explicitly if you have registered your dapp at developer dashboard. originData contains a signature of dapp's origin url which is generated using project's secret.
loginConfigloginConfig enables you to pass your own login verifiers configuration for various loginProviders. loginConfig is key value map where each key should be a valid loginProvider and value should be custom configuration for that loginProvider. You can deploy your own verifiers from developer dashboard to use here.
whiteLabeloptions for whitelabling default auth modal screens.
storageServerUrlSpecify a custom storage server url
storageKeysetting to "local" will persist social login session across browser tabs.
sessionTimeThis is the sessionTime for the login session
mfaSettingsThis parameter will be used to enable mfa factors and set priority on UI listing. List of factors available deviceShareFactor | backUpShareFactor | socialBackupFactor | passwordFactor | passkeysFactor | authenticatorFactor
useCoreKitKeySetting this boolean value to true will get you the core kit key.
mfaSettings​
note

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

Backup MFA Options

Usage
import { AuthAdapter } from "@web3auth/auth-adapter";

const authAdapter = new AuthAdapter({
  loginSettings: {
    mfaLevel: "mandatory", // default, optional, mandatory, none
  },
  adapterSettings: {
    // SCALE and above plan only feature
    mfaSettings: {
      deviceShareFactor: {
        enable: true,
        priority: 1,
        mandatory: true, // at least two factors are mandatory
      },
      backUpShareFactor: {
        enable: true,
        priority: 2,
        mandatory: true, // at least two factors are mandatory
      },
      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,
      },
    },
  },
});
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.