Skip to main content

Custom Authentication with PnP Web Modal SDK

Custom Authentication is a way to authenticate users with your custom authentication service. For example, while authenticating with Google, you can use your own Google Client ID to authenticate users directly.

To enable this, you need to Create a Verifier from the Custom Authentication tab of your project from the Web3Auth Developer Dashboard with your desired configuration.

note

This is a paid feature and the minimum pricing plan to use this SDK in a production environment is the Growth Plan. You can use this feature in Web3Auth Sapphire Devnet network for free.

warning

For Custom JWT-based authentication services, you need to use the Web3Auth Plug and Play NoModal SDK, since the Web3Auth Modal will only help you configure the social logins present within the Modal UI.

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 adapterSettings configuration which enables you to make changes in the adapter, enabling you to do things like Whitelabeling and Custom Authentication among other things.

tip

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

Further, the loginConfig parameter of the adapterSettings configuration helps us to customize the social logins. Since we're using the @web3auth/modal, ie. the Plug and Play Modal SDK, the loginConfig should correspond to the socials mentioned in the modal.

loginConfig​

The loginConfig parameter of adapterSettings in AuthAdapter 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

Example​

Since we're using the @web3auth/modal ie. the Plug and Play Modal SDK, the loginConfig should correspond to the socials mentioned in the modal.

Single Verifier​

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);

Aggregate Verifier​

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

const authAdapter = new AuthAdapter({
  adapterSettings: {
    loginConfig: {
      // Google login
      google: {
        verifier: "YOUR_AGGREGATE_VERIFIER_NAME", // Please create an aggregate verifier on the developer dashboard and pass the name here
        verifierSubIdentifier: "YOUR_SUB_VERIFIER_NAME", // Pass in the sub verifier name here
        typeOfLogin: "google", // Pass on the login provider of the verifier you've created
        clientId: "YOUR_GOOGLE_CLIENT_ID", // based on sub verifier, pass in the clientId of the login provider here - Please note this differs from the Web3Auth ClientID.
      },
      github: {
        verifier: "YOUR_AGGREGATE_VERIFIER_NAME", // Please create an aggregate verifier on the developer dashboard and pass the name here
        verifierSubIdentifier: "YOUR_SUB_VERIFIER_NAME", // Pass in the sub verifier name here
        typeOfLogin: "github", // Pass on the login provider of the verifier you've created
        clientId: "YOUR_GITHUB_CLIENT_ID", // based on sub verifier, pass in the clientId of the login provider here - Please note this differs from the Web3Auth ClientID.
        jwtParameters: {
          domain: "YOUR_AUTH0_DOMAIN",
          verifierIdField: "YOUR_AUTH0_VERIFIER_ID_FIELD",
          isVerifierIdCaseSensitive: true, // only if the verifier id is case sensitive, else remove this line
        },
      },
    },
  },
  privateKeyProvider,
});
web3auth.configureAdapter(authAdapter);