Skip to main content

Auth Adapter for Social Logins

@web3auth/auth-adapter​

The default adapter of Web3Auth is the auth-adapter. This adapter is a wrapper around the auth library from Web3Auth (previously Torus) and enables the main social login features of Web3Auth. By default, Web3Auth has certain configuration set to enable a quick integration, however, for customising features, like Whitelabel, Custom Authentication, etc. you need to customise the Auth Adapter. With the Auth Adapter package installed and instantiated, you can explore a number of options and can customise the login experience of the user as per your needs.

Basic Details​

Adapter Name: auth​

Package Name: @web3auth/auth-adapter​

Default: YES​

Installation​

npm install --save @web3auth/auth-adapter

Instantiation​

Import the AuthAdapter class from @web3auth/auth-adapter​

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

Assign the AuthAdapter class to a variable​

const authAdapter = new AuthAdapter(AuthAdapterOptions);

This AuthAdapter constructor takes an object with AuthAdapterOptions as input.

Arguments​

AuthAdapterOptions​

Parametertype
adapterSettings?authOptions
loginSettings?LoginSettings
privateKeyProvider?PrivateKeyProvider

Auth Adapter Settings​

adapterSettings​

AuthOptions​
VariableTypeDescriptionMandatoryDefault Value
clientIdstringYou can get your clientId/projectId by registering your dapp on developer dashboardYes-
networkWEB3AUTH_NETWORK_TYPEnetwork specifies the web3auth network to be used.Yes-
buildEnvBUILD_ENV_TYPEThis parameter will be used to change the build environment of auth sdk.Noproduction
redirectUrlstringredirectUrl is the dapp's url where user will be redirected after login. Register this url at developer dashboard else initialization will give error.No-
uxModeUX_MODE_TYPEtwo 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.No'POPUP'
replaceUrlOnRedirectbooleanreplaceUrlOnRedirect removes the params from the redirected url after loginNotrue
originDataOriginDataoriginData 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.No-
loginConfigLoginConfigloginConfig 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.No-
webauthnTransportsAuthenticatorTransport[]webauthnTransport enables you to configure the transport type user can use for saving their share. This is only available for v1 users.No["internal"]
sdkUrlstringsdkUrl is for internal development use only and is used to override the network parameter.No-
dashboardUrlstringdashboardUrl is for internal development use only and is used to override the buildEnv parameter.No-
whiteLabelWhiteLabelDataoptions for whitelabling default auth modal.No-
storageServerUrlstringSpecify a custom storage server urlNohttps://session.web3auth.io
storageKey"session" | "local"setting to "local" will persist social login session across browser tabs.No"local"
sessionTimenumberHow long should a login session last at a minimum in secondsNo86400 seconds
sessionNamespacestringThis option is for internal use only in torus wallet and has no effect on user's login on other dapps.No-
mfaSettingsMfaSettingsThis parameter will be used to enable mfa factors and set priority on UI listing. List of factors available backUpShareFactor | socialFactor | passwordFactor | authenticatorFactorNofalse
useMpcbooleanThis parameter will be used to use auth mpcNofalse
useCoreKitKeybooleanThis parameter will be used to select core kit key.Nofalse

Login Settings​

loginSettings​

warning

While you can pass your chainConfig to AuthAdapter, it is not required for web3auth/no-modal ie. The Web3Auth Plug and Play No Modal package, since you can directly pass loginParams over to the connectTo function.

Either way, both of these methods will work the same. Please note that the connectTo function params will override the AuthAdapter settings.

Read more about how to pass loginParams to connectTo in its respective section: web3auth/no-modal

LoginSettings​
VariableDescription
loginProviderloginProvider sets the oauth login method to be used. You can use any of the valid loginProvider from the supported list.
mfaLevelYou 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 none @defaultValue none
getWalletKeyThis option is for internal use only in torus wallet and has no effect on user's login on other dapps. Defaults to false @defaultValue false @internal
extraLoginOptionsextraLoginOptions 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
dappShareCustom 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
curveThis 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.
dappUrlAllows the dapp to set a custom redirect url for the manage mfa flow.

Multi-Factor Authentication​

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 help log 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

We offer the following backup factors under 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.

  • deviceShareFactor,
  • backUpShareFactor,
  • socialBackupFactor,
  • passwordFactor,
  • authenticatorFactor, and
  • passkeysFactor.

Example​

const authAdapter = new AuthAdapter({
  loginSettings: {
    mfaLevel: "optional", // default, optional, mandatory, none
  },
  adapterSettings: {
    // SCALE and above plan only feature
    mfaSettings: {
      deviceShareFactor: {
        enable: true,
        priority: 1,
        mandatory: true,
      },
      backUpShareFactor: {
        enable: true,
        priority: 2,
        mandatory: false,
      },
      socialBackupFactor: {
        enable: true,
        priority: 3,
        mandatory: false,
      },
      passwordFactor: {
        enable: true,
        priority: 4,
        mandatory: false,
      },
      authenticatorFactor: {
        enable: true,
        priority: 5,
        mandatory: false,
      },
      passkeysFactor: {
        enable: true,
        priority: 6,
        mandatory: false,
      },
    },
  },
});

Whitelabel​

Web3Auth's Social Logins and Email Login run using the Auth Flow. The whole Auth user experience can also be whitelabeled using Auth Adapter settings. For this, you need to pass on the whiteLabel configuration parameter to the adapterSettings property of the auth-adapter.

whiteLabel?: WhiteLabelData;​

The whitelabel parameter takes WhitelabelData as input. The WhitelabelData object takes the following parameters:

WhiteLabelData

ParameterDescription
appNameApp name to display in the UI
appUrlApp url
logoLightApp logo to use in light mode
logoDarkApp logo to use in dark mode
defaultLanguagelanguage which will be used by web3auth. app will use browser language if not specified. if language is not supported it will use "en"
modetheme
useLogoLoaderUse logo loader
themeUsed to customize your theme
tncLinkLanguage specific link for terms and conditions on torus-website. See (examples/vue-app) to configure
privacyPolicyLanguage specific link for privacy policy on torus-website. See (examples/vue-app) to configure

Example​

import { AuthAdapter, WHITE_LABEL_THEME, WhiteLabelData } from "@web3auth/auth-adapter";
import {
  CHAIN_NAMESPACES,
  IProvider,
  UX_MODE,
  WALLET_ADAPTERS,
  WEB3AUTH_NETWORK,
} from "@web3auth/base";

const authAdapter = new AuthAdapter({
  adapterSettings: {
    clientId, //Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    uxMode: UX_MODE.REDIRECT,
    whiteLabel: {
      appName: "W3A Heroes",
      appUrl: "https://web3auth.io",
      logoLight: "https://web3auth.io/images/web3auth-logo.svg",
      logoDark: "https://web3auth.io/images/web3auth-logo---Dark.svg",
      defaultLanguage: "en", // en, de, ja, ko, zh, es, fr, pt, nl, tr
      mode: "dark", // whether to enable dark mode. defaultValue: auto
      theme: {
        primary: "#00D1B2",
      } as WHITE_LABEL_THEME,
      useLogoLoader: true,
    } as WhiteLabelData,
  },
  privateKeyProvider,
});
web3auth.configureAdapter(authAdapter);

Custom Authentication​

While instantiating the Auth Adapter, you can pass some configuration objects to the constructor. One of these configurations is the adapterSettings configuration which enables you to make changes in the adapter, enabling you to do things like Whitelabeling and Custom Authentication among other things.

loginConfig​

The loginConfig parameter of adapterSettings in auth-adapter contains the following properties:

loginConfig: { "identifier of social login": { params } }

params

ParameterDescription
verifier
typeOfLoginThe type of login. Refer to enum LOGIN_TYPE
nameDisplay Name. If not provided, we use the default for auth app
descriptionDescription for button. If provided, it renders as a full length button. else, icon button
clientIdCustom client_id. If not provided, we use the default for auth app
verifierSubIdentifierThe field in JWT token which maps to verifier id. Please make sure you selected correct JWT verifier id in the developer dashboard. It accepts string as a value.
logoHoverLogo to be shown on mouse hover. If not provided, we use the default for auth app
logoLightLogo to be shown on dark background (dark theme). If not provided, we use the default for auth app
logoDarkLogo to be shown on light background (light theme). If not provided, we use the default for auth app
mainOptionShow login button on the main list
showOnModalWhether to show the login button on modal or not
showOnDesktopWhether to show the login button on desktop
showOnMobileWhether to show the login button on mobile
showOnSocialBackupFactorIf 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.
jwtParametersCustom jwt parameters to configure the login. Useful for Auth0 configuration

Custom Authentication within Web3Auth Modal​

When we're using the @web3auth/modal, ie. the Plug and Play Modal SDK, the loginConfig should correspond to the socials mentioned in the modal. This means you can use your own authentication services for the following services:

google | facebook | twitter | reddit | discord | twitch | apple | line | github | kakao | linkedin | weibo | wechat | passwordless

info

You can customize all or a few of the social logins and others will remain default. You can also remove the ones you don't want using the whitelabeling option.

Example​

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

const authAdapter = new AuthAdapter({
  adapterSettings: {
    loginConfig: {
      // Google login
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME", // Please create a verifier on the developer dashboard and pass the name here
        typeOfLogin: "google", // Pass on the login provider of the verifier you've created
        clientId: "GOOGLE_CLIENT_ID.apps.googleusercontent.com", // Pass on the clientId of the login provider here - Please note this differs from the Web3Auth ClientID. This is the JWT Client ID
      },
    },
  },
  privateKeyProvider,
});
web3auth.configureAdapter(authAdapter);

Logging in through your Custom JWT Token​

When we are using @web3auth/no-modal, ie. Web3Auth Plug and Play No Modal SDK, we have the option to use the connectTo function, which enables you to customize the login process according to the parameters you have for your custom authentication service.

connectTo()​

To log a user in the Web3Auth Plug and Play No Modal SDK, you need to call the connectTo() function. This function helps you customize the login process according to your own needs, by taking the following parameters:

VariableDescription
walletNameWallet Adapter you want to use for logging in your user. It accepts WALLET_ADAPTER_TYPE.
loginParams?Login parameters specific to your wallet adapter. Although this is defined as a generic type T, you can use AuthLoginParams as a reference for typical parameters.
tip

Know more about the connectTo function in the Usage SDK Reference

Further, to enable Custom Authentication, the loginParams parameter takes in another object called extraLoginOptions which contains the following properties:

ExtraLoginOptions​
ParameterDescription
domainYour Auth0 account domain such as 'example.auth0.com', 'example.eu.auth0.com' or , 'example.mycompany.com' (when using custom domains)
client_idThe Client ID found on your Application settings page
redirect_uriThe default URL where Auth0 will redirect your browser to with the authentication result. It must be whitelisted in the "Allowed Callback URLs" field in your Auth0 Application's settings. If not provided here, it should be provided in the other methods that provide authentication.
leewayThe value in seconds used to account for clock skew in JWT expirations. Typically, this value is no more than a minute or two at maximum. Defaults to 60s.
verifierIdFieldThe field in jwt token which maps to verifier id
isVerifierIdCaseSensitiveWhether the verifier id field is case sensitive
additionalParamsIf you need to send custom parameters to the Authorization Server, make sure to use the original parameter name.
display- 'page': displays the UI with a full page view - 'popup': displays the UI with a popup window - 'touch': displays the UI in a way that leverages a touch interface - 'wap': displays the UI with a "feature phone" type interface
prompt- 'none': do not prompt user for login or consent on re-authentication - 'login': prompt user for re-authentication - 'consent': prompt user for consent before processing request - 'select_account': prompt user to select an account
max_ageMaximum allowable elapsed time (in seconds) since authentication. If the last time the user authenticated is greater than this value, the user must be re-authenticated.
ui_localesThe space-separated list of language tags, ordered by preference. For example: 'fr-CA fr en'.
id_token_hintPreviously issued ID Token.
login_hintThe user's email address or other identifier. When your app knows which user is trying to authenticate, you can provide this parameter to pre-fill the email box or select the right session for sign-in. This currently only affects the classic Lock experience.
acr_values
scopeThe default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope
audienceThe default audience to be used for requesting API access.
connectionThe name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget.

Example​

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

const authAdapter = new AuthAdapter({
  adapterSettings: {
    loginConfig: {
      jwt: {
        verifier: "YOUR-VERIFIER-NAME-ON-WEB3AUTH-DASHBOARD",
        typeOfLogin: "jwt",
        clientId: "YOUR-CLIENTID-FROM-LOGIN-PROVIDER",
      },
    },
  },
  privateKeyProvider,
});

web3auth.configureAdapter(authAdapter);
import { WALLET_ADAPTERS } from "@web3auth/base";
// inside your async function with on click handler
const web3authProvider = await web3auth.connectTo(WALLET_ADAPTERS.AUTH, {
  loginProvider: "google",
});

Initialization​

Finally, once all the configurations are set, you need to initialize the Auth Adapter.

web3auth.configureAdapter(authAdapter);

Change Adapter Settings​

You can change the adapter settings by calling the setAdapterSettings() function on the adapter instance. This function takes the below-mentioned parameters as well as

Auth Adapter Settings.

Arguments​

AuthOptions

Parametertypedescription
clientIdstringYour projectId/clientId from the dashboard
networkWEB3AUTH_NETWORK_TYPENetwork specifies the web3auth network to be used.
buildEnv?BUILD_ENV_TYPEThis parameter will be used to change the build environment of auth sdk.
redirectUrl?stringredirectUrl is the dapp's url where user will be redirected after login. Register this url at "https://dashboard.web3auth.io" else initialization will give error.
uxMode?UX_MODE_TYPEEither of the two uxMode values: popup or redirect. Use of REDIRECT mode is recommended in browsers where popups might get blocked.
replaceUrlOnRedirect?booleanreplaceUrlOnRedirect removes the params from the redirected url after login
originData?OriginDataoriginData contains a signature of dapp's origin url which is generated using project's secret.
loginConfig?LoginConfigloginConfig is key value map where each key should be a valid loginProvider and value should be custom configuration for that loginProvider.
webauthnTransports?AuthenticatorTransport[]webauthnTransports enables you to configure the transport type user can use for saving their share.
whiteLabel?WhiteLabelDatawhiteLabel is for whitelabling default auth modal.
storageServerUrl?stringstorageServerUrl specifies a custom storage server url
storageKey?"session" | "local"storageKey setting to local will persist social login session across browser tabs.
sessionTime?numberHow long should a login session last at a minimum in seconds. Maximum value of sessionTime can be 7 * 86400 (7 days)
mfaSettings?MfaSettingsThis parameter will be used to enable mfa factors and set priority on UI listing.
useMpc?booleanThis parameter will be used to use auth mpc
useCoreKitKey?booleanThis parameter will be used to select core kit key.

BaseAdapterSettings

Parametertype
clientIdstring
sessionTimenumber
chainConfigCustomChainConfig
web3AuthNetworkWEB3AUTH_NETWORK_TYPE
useCoreKitKeyboolean

Example​

@web3auth/modal​

const authAdapter = new AuthAdapter({
  adapterSettings: {
    uxMode: "redirect", // "redirect" | "popup"
    whiteLabel: {
      logoLight: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoDark: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
      defaultLanguage: "en", // en, de, ja, ko, zh, es, fr, pt, nl, tr
      mode: "dark", // whether to enable dark, light or auto mode. defaultValue: auto [ system theme]
    },
    // SCALE and above plan only feature
    mfaSettings: {
      deviceShareFactor: {
        enable: true,
        priority: 1,
        mandatory: true,
      },
      backUpShareFactor: {
        enable: true,
        priority: 2,
        mandatory: false,
      },
      socialBackupFactor: {
        enable: true,
        priority: 3,
        mandatory: false,
      },
      passwordFactor: {
        enable: true,
        priority: 4,
        mandatory: false,
      },
    },
    loginConfig: {
      // Add login configs corresponding to the providers on modal
      // Google login
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME", // Please create a verifier on the developer dashboard and pass the name here
        typeOfLogin: "google", // Pass on the login provider of the verifier you've created
        clientId: "GOOGLE_CLIENT_ID.apps.googleusercontent.com", // Pass on the clientId of the login provider here - Please note this differs from the Web3Auth ClientID. This is the JWT Client ID
      },
      // Facebook login
      facebook: {
        verifier: "YOUR_FACEBOOK_VERIFIER_NAME", // Please create a verifier on the developer dashboard and pass the name here
        typeOfLogin: "facebook", // Pass on the login provider of the verifier you've created
        clientId: "FACEBOOK_CLIENT_ID_1234567890", // Pass on the clientId of the login provider here - Please note this differs from the Web3Auth ClientID. This is the JWT Client ID
      },
      // Add other login providers here
    },
  },
  loginSettings: {
    mfaLevel: "mandatory",
  },
});
web3auth.configureAdapter(authAdapter);

// You can change the adapter settings by calling the `setAdapterSettings()` function on the adapter instance.

authAdapter.setAdapterSettings({
  web3AuthNetwork: "sapphire_mainnet",
  sessionTime: 3600, // 1 hour in seconds
  chainConfig: {
    chainNamespace: CHAIN_NAMESPACES.EIP155,
    chainId: "0x1",
    rpcTarget: "https://rpc.ankr.com/eth", // This is the public RPC we have added, please pass on your own endpoint while creating an app
  },
  clientId,
  redirectUrl: "http://localhost:3000",
});

web3auth/no-modal​

const authAdapter = new AuthAdapter({
  adapterSettings: {
    network: "sapphire_mainnet",
    uxMode: "popup",
    whiteLabel: {
      appName: "W3A Heroes",
      appUrl: "https://web3auth.io",
      logoLight: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoDark: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
      defaultLanguage: "en", // en, de, ja, ko, zh, es, fr, pt, nl, tr
      mode: "auto", // whether to enable dark mode. defaultValue: false
      theme: {
        primary: "#768729",
      },
      useLogoLoader: true,
    },
    // SCALE and above plan only feature
    mfaSettings: {
      deviceShareFactor: {
        enable: true,
        priority: 1,
        mandatory: true,
      },
      backUpShareFactor: {
        enable: true,
        priority: 2,
        mandatory: false,
      },
      socialBackupFactor: {
        enable: true,
        priority: 3,
        mandatory: false,
      },
      passwordFactor: {
        enable: true,
        priority: 4,
        mandatory: false,
      },
    },
    loginConfig: {
      jwt: {
        verifier: "web3auth-auth0-demo",
        typeOfLogin: "jwt",
        clientId: "294QRkchfq2YaXUbPri7D6PH7xzHgQMT",
      },
    },
  },
});
web3auth.configureAdapter(authAdapter);

// You can change the adapter settings by calling the `setAdapterSettings()` function on the adapter instance.

authAdapter.setAdapterSettings({
  web3AuthNetwork: "sapphire_mainnet",
  sessionTime: 3600, // 1 hour in seconds
  chainConfig: {
    chainNamespace: CHAIN_NAMESPACES.EIP155,
    chainId: "0x1",
    rpcTarget: "https://rpc.ankr.com/eth", // This is the public RPC we have added, please pass on your own endpoint while creating an app
  },
  clientId,
  redirectUrl: "http://localhost:3000",
});