Multi Factor Authentication with PnP Web No 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 loginoptional
: presents the MFA screen on every login, but you can skip itmandatory
: make it mandatory to set up MFA after loginnone
: skips the MFA setup screen
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.
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 sapphire_devnet
for free.
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
- Yarn
- pnpm
npm install --save @web3auth/auth-adapter
yarn add @web3auth/auth-adapter
pnpm add @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.
Checkout the auth-adapter
SDK Reference for more details on
different configurations you can pass for customisations.
Login Settings
loginSettings
- Table
- Type Declaration
Variable | Description |
---|---|
loginProvider | Sets 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:
|
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 and domain as your app domain in extraLoginOptions while using email_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 . 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. |
export type LoginSettings = Partial<LoginParams> & Partial<BaseRedirectParams>;
export type LoginParams = BaseRedirectParams & {
/**
* loginProvider sets the oauth login method to be used.
* You can use any of the valid loginProvider from the supported list.
*/
loginProvider: LOGIN_PROVIDER_TYPE | CUSTOM_LOGIN_PROVIDER_TYPE;
/**
* 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
*
* Defaults to `default`
* @defaultValue `default`
*/
mfaLevel?: MfaLevelType;
/**
* extraLoginOptions can be used to pass standard oauth login options to
* loginProvider.
*
* For ex: you will have to pass `login_hint` as user's email and `domain`
* as your app domain in `extraLoginOptions` while using `email_passwordless`
* loginProvider
*/
extraLoginOptions?: ExtraLoginOptions;
/**
* 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
*/
dappShare?: string;
/**
* 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`. As of now you have to convert it to `'ed25519'` if you want.
* You can use `@toruslabs/openlogin-ed25519` npm package for this purpose.
*
*
* @defaultValue secp256k1
*/
curve?: SUPPORTED_KEY_CURVES_TYPE;
};
export declare type BaseRedirectParams = {
/**
* redirectUrl is the dapp's url where user will be redirected after login.
*
* @remarks
* Register this url at {@link "https://dashboard.web3auth.io"| developer dashboard}
* else initialization will give error.
*/
redirectUrl?: string;
/**
* 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.
*/
appState?: string;
};
/**
* {@label loginProviderType}
*/
export declare type LOGIN_PROVIDER_TYPE = (typeof LOGIN_PROVIDER)[keyof typeof LOGIN_PROVIDER];
export declare const LOGIN_PROVIDER: {
readonly GOOGLE: "google";
readonly FACEBOOK: "facebook";
readonly REDDIT: "reddit";
readonly DISCORD: "discord";
readonly TWITCH: "twitch";
readonly APPLE: "apple";
readonly LINE: "line";
readonly GITHUB: "github";
readonly KAKAO: "kakao";
readonly LINKEDIN: "linkedin";
readonly TWITTER: "twitter";
readonly WEIBO: "weibo";
readonly WECHAT: "wechat";
readonly EMAIL_PASSWORDLESS: "email_passwordless";
readonly SMS_PASSWORDLESS: "sms_passwordless";
readonly WEBAUTHN: "webauthn";
readonly JWT: "jwt";
};
export type CUSTOM_LOGIN_PROVIDER_TYPE = string & {
toString?: (radix?: number) => string;
};
/**
* {@label MfaLevelType}
*/
export declare type MfaLevelType = (typeof MFA_LEVELS)[keyof typeof MFA_LEVELS];
export declare const MFA_LEVELS: {
readonly DEFAULT: "default";
readonly OPTIONAL: "optional";
readonly MANDATORY: "mandatory";
readonly NONE: "none";
};
/**
* {@label SUPPORTED_KEY_CURVES_TYPE}
*/
export declare type SUPPORTED_KEY_CURVES_TYPE =
(typeof SUPPORTED_KEY_CURVES)[keyof typeof SUPPORTED_KEY_CURVES];
export declare const SUPPORTED_KEY_CURVES: {
readonly SECP256K1: "secp256k1";
readonly ED25519: "ed25519";
};
import { AuthAdapter } from "@web3auth/auth-adapter";
const authAdapter = new AuthAdapter({
loginSettings: {
mfaLevel: "mandatory", // default, optional, mandatory, none
},
});
Adapter Settings
adapterSettings
- Table
- Type Declaration
Variable | Description |
---|---|
clientId | You can get your clientId/projectId by registering your dapp on developer dashboard |
network | network specifies the web3auth network to be used. |
buildEnv | This parameter will be used to change the build environment of auth sdk. |
redirectUrl | redirectUrl is the dapp's url where user will be redirected after login. Register this url at developer dashboard else initialization will give error. |
uxMode | two uxModes are supported:- - 'POPUP' : In this uxMode, a popup will be shown to user for login. - '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. |
replaceUrlOnRedirect | replaceUrlOnRedirect removes the params from the redirected url after login |
originData | originData 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. |
loginConfig | loginConfig 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. |
webauthnTransports | webauthnTransport enables you to configure the transport type user can use for saving their share. This is only available for v1 users. |
sdkUrl | sdkUrl is for internal development use only and is used to override the network parameter. |
dashboardUrl | dashboardUrl is for internal development use only and is used to override the buildEnv parameter. |
whiteLabel | options for whitelabling default auth modal. |
storageServerUrl | Specify a custom storage server url |
storageKey | setting to "local" will persist social login session across browser tabs. How long should a login session last at a minimum in seconds |
sessionTime | How long should a login session last at a minimum in seconds |
sessionNamespace | This option is for internal use only in torus wallet and has no effect on user's login on other dapps. |
mfaSettings | This parameter will be used to enable mfa factors and set priority on UI listing. List of factors available backUpShareFactor | socialFactor | passwordFactor | authenticatorFactor |
useMpc | This parameter will be used to use auth mpc |
useCoreKitKey | This parameter will be used to select core kit key. |
adapterSettings?: MakeOptional<AuthOptions, "clientId" | "network"> & {
useCoreKitKey?: boolean;
};
export type AuthOptions = {
/**
* You can get your clientId/projectId by registering your
* dapp on {@link "https://dashboard.web3auth.io"| developer dashboard}
*/
clientId: string;
/**
* network specifies the web3auth network to be used.
*/
network: WEB3AUTH_NETWORK_TYPE;
/**
* This parameter will be used to change the build environment of auth sdk.
* @defaultValue production
*/
buildEnv?: BUILD_ENV_TYPE;
/**
* redirectUrl is the dapp's url where user will be redirected after login.
*
* @remarks
* Register this url at {@link "https://dashboard.web3auth.io"| developer dashboard}
* else initialization will give error.
*/
redirectUrl?: string;
/**
* two uxModes are supported:-
* - `'POPUP'`: In this uxMode, a popup will be shown to user for login.
* - `'REDIRECT'`: In this uxMode, user will be redirected to a new window tab for login.
*
* @defaultValue `'POPUP'`
* @remarks
*
* Use of `'REDIRECT'` mode is recommended in browsers where popups might get blocked.
*/
uxMode?: UX_MODE_TYPE;
/**
* replaceUrlOnRedirect removes the params from the redirected url after login
*
* @defaultValue true
*/
replaceUrlOnRedirect?: boolean;
/**
* originData is used to verify the origin of dapp by iframe.
*
* @internal
* @remarks
* You don't have to pass originData explicitly if you have registered your dapp at
* {@link "https://dashboard.web3auth.io"| developer dashboard}.
*
* originData contains a signature of dapp's origin url which is generated using
* project's secret.
*/
originData?: OriginData;
/**
* loginConfig 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
*
* @remarks
* You can deploy your own verifiers from {@link "https://dashboard.web3auth.io"| developer dashboard}
* to use here.
*
*/
loginConfig?: LoginConfig;
/**
* webauthnTransport enables you to configure the transport type user can use
* for saving their share.
*
* @defaultValue ["internal"]
*
* @remarks
* This is only available for v1 users.
*/
webauthnTransports?: AuthenticatorTransport[];
/**
* sdkUrl is for internal development use only and is used to override the
* `network` parameter.
* @internal
*/
sdkUrl?: string;
/**
* dashboardUrl is for internal development use only and is used to override the
* `buildEnv` parameter.
* @internal
*/
dashboardUrl?: string;
/**
* options for whitelabling default auth modal.
*/
whiteLabel?: WhiteLabelData;
/**
* Specify a custom storage server url
* @defaultValue https://session.web3auth.io
* @internal
*/
storageServerUrl?: string;
/**
* setting to "local" will persist social login session across browser tabs.
*
* @defaultValue "local"
*/
storageKey?: "session" | "local";
/**
* How long should a login session last at a minimum in seconds
*
* @defaultValue 86400 seconds
* @remarks Max value of sessionTime can be 7 * 86400 (7 days)
*/
sessionTime?: number;
/**
* This option is for internal use only in torus wallet and has no effect
* on user's login on other dapps.
* @internal
*/
sessionNamespace?: string;
/**
* This parameter will be used to enable mfa factors and set priority on UI listing.
* List of factors available
* backUpShareFactor | socialFactor | passwordFactor | authenticatorFactor
* @defaultValue false
*/
mfaSettings?: MfaSettings;
/**
* This parameter will be used to use auth mpc
* @defaultValue false
*/
useMpc?: boolean;
/**
* This parameter will be used to select core kit key.
* @defaultValue false
*/
useCoreKitKey?: boolean;
};
export type LoginConfig = Record<string, {
verifier: string;
/**
* The type of login. Refer to enum `LOGIN_TYPE`
*/
typeOfLogin: TypeOfLogin;
/**
* Display Name. If not provided, we use the default for auth app
*/
name?: string;
/**
* Description for button. If provided, it renders as a full length button. else, icon button
*/
description?: string;
/**
* Custom client_id. If not provided, we use the default for auth app
*/
clientId?: string;
verifierSubIdentifier?: string;
/**
* Logo to be shown on mouse hover. If not provided, we use the default for auth app
*/
logoHover?: string;
/**
* Logo to be shown on dark background (dark theme). If not provided, we use the default for auth app
*/
logoLight?: string;
/**
* Logo to be shown on light background (light theme). If not provided, we use the default for auth app
*/
logoDark?: string;
/**
* Show login button on the main list
*/
mainOption?: boolean;
/**
* Whether to show the login button on modal or not
*/
showOnModal?: boolean;
/**
* Whether to show the login button on desktop
*/
showOnDesktop?: boolean;
/**
* Whether to show the login button on mobile
*/
showOnMobile?: boolean;
/**
* If we are using social logins as a backup factor,
* then this option will be used to show the type of social login
* on the social backup login screen.
*/
showOnSocialBackupFactor?: boolean;
/**
* Custom jwt parameters to configure the login. Useful for Auth0 configuration
*/
jwtParameters?: JwtParameters;
}>;
export type WhiteLabelData = {
/**
* App name to display in the UI
*/
appName?: string;
/**
* App url
*/
appUrl?: string;
/**
* App logo to use in light mode
*/
logoLight?: string;
/**
* App logo to use in dark mode
*/
logoDark?: string;
/**
* language which will be used by web3auth. app will use browser language if not specified. if language is not supported it will use "en"
* en: english
* de: german
* ja: japanese
* ko: korean
* zh: mandarin
* es: spanish
* fr: french
* pt: portuguese
* nl: dutch
* tr: turkish
*
* @defaultValue en
*/
defaultLanguage?: LANGUAGE_TYPE;
/**
theme
*
* @defaultValue light
*/
mode?: THEME_MODE_TYPE;
/**
* Use logo loader
*
* @defaultValue false
*/
useLogoLoader?: boolean;
/**
* Used to customize your theme
*/
theme?: WHITE_LABEL_THEME;
/**
* Language specific link for terms and conditions on torus-website. See (examples/vue-app) to configure
* e.g.
* tncLink: {
* en: "http://example.com/tnc/en",
* ja: "http://example.com/tnc/ja",
* }
*/
tncLink?: Partial<Record<LANGUAGE_TYPE, string>>;
/**
* Language specific link for privacy policy on torus-website. See (examples/vue-app) to configure
* e.g.
* privacyPolicy: {
* en: "http://example.com/tnc/en",
* ja: "http://example.com/tnc/ja",
* }
*/
privacyPolicy?: Partial<Record<LANGUAGE_TYPE, string>>;
};
export declare const MFA_FACTOR: {
readonly DEVICE: "deviceShareFactor";
readonly BACKUP_SHARE: "backUpShareFactor";
readonly SOCIAL_BACKUP: "socialBackupFactor";
readonly PASSWORD: "passwordFactor";
readonly PASSKEYS: "passkeysFactor";
readonly AUTHENTICATOR: "authenticatorFactor";
};
export type MFA_FACTOR_TYPE = (typeof MFA_FACTOR)[keyof typeof MFA_FACTOR];
export type MFA_SETTINGS = {
enable: boolean;
priority?: number;
mandatory?: boolean;
};
export type MfaSettings = Partial<Record<MFA_FACTOR_TYPE, MFA_SETTINGS>>;
mfaSettings
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 sapphire_devnet
for free.
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,
},
},
},
});
- 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 andmandatory: 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.