Skip to main content

Web3Auth v10 Custom Authentication Migration Guide

This guide focuses specifically on migrating custom authentication configurations from Web3Auth v7 to v10. This covers the transition from "Verifiers" to "Connections" and "Grouped Connections". This is a supplementary guide to the main v7 to v10 migration guide.

Overview​

In v7, custom authentication used verifier and aggregate verifier configurations for linking accounts from different social providers to the same underlying user wallet. In v10, this system is streamlined with "Connections" and "Grouped Connections" configured on the Web3Auth Developer Dashboard, significantly reducing client-side code complexity.

Key Changes & Mapping​

1. Single Verifiers (v7) to Single Connections (v10)​

Single verifiers in v7 become connections in v10:

const openloginAdapter = new OpenloginAdapter({
  adapterSettings: {
    loginConfig: {
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME", // v7 verifier name
        typeOfLogin: "google",
        clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
      },
    },
  },
});

web3auth.configureAdapter(openloginAdapter);
await web3auth.initModal();

const web3AuthOptions: Web3AuthOptions = {
  clientId: "YOUR_CLIENT_ID",
  // ...
  modalConfig: {
    connectors: {
      [WALLET_CONNECTORS.AUTH]: {
        loginMethods: {
          google: {
            name: "Google Login",
            authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID", // v10 connection ID
          },
        },
      },
    },
  },
};

// OR v10: connectTo with a single connection
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
//   authConnection: AUTH_CONNECTION.GOOGLE,
//   authConnectionId: "YOUR_GOOGLE_AUTH_CONNECTION_ID",
// });

Action​

Your existing v7 single verifiers will be automatically migrated to "Connections" on the new Web3Auth Developer Dashboard. Locate your migrated Connection, note its authConnectionId, and use this ID in your v10 client code (modalConfig or connectTo). Remove any v7 OpenloginAdapter configuration previously used for this verifier.

2. Aggregate Verifiers (v7) to Grouped Connections (v10)​

Aggregate verifiers in v7 become grouped connections in v10:

const openloginAdapter = new OpenloginAdapter({
  adapterSettings: {
    loginConfig: {
      google: {
        // Part of an aggregate verifier
        verifier: "MY_AGGREGATE_VERIFIER_NAME", // Main aggregate verifier name
        verifierSubIdentifier: "google-sub-verifier", // Specific sub-verifier for Google
        typeOfLogin: "google",
        clientId: "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
      },
      jwt_email: {
        // Another part of the same aggregate verifier
        verifier: "MY_AGGREGATE_VERIFIER_NAME",
        verifierSubIdentifier: "custom-jwt-sub-verifier",
        typeOfLogin: "jwt",
        clientId: "YOUR_CUSTOM_JWT_CLIENT_ID", // Not always applicable for JWT
        jwtParameters: {
          /* ... JWT specific params like domain, verifierIdField ... */
        },
      },
    },
  },
});

web3auth.configureAdapter(openloginAdapter);
await web3auth.initModal();

const web3AuthOptions: Web3AuthOptions = {
  clientId: "YOUR_CLIENT_ID",
  // ...
  modalConfig: {
    connectors: {
      [WALLET_CONNECTORS.AUTH]: {
        loginMethods: {
          google: {
            name: "Google Login",
            authConnectionId: "YOUR_INDIVIDUAL_GOOGLE_CONNECTION_ID", // ID of the individual Google connection
            groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD", // ID of the group
          },
          myCustomJWT: {
            name: "Login with Corp Email",
            authConnectionId: "YOUR_INDIVIDUAL_CUSTOM_JWT_CONNECTION_ID",
            groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
          },
        },
      },
    },
  },
};

// OR v10: connectTo with a grouped connection
// For Google login part of the group:
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
//   authConnection: AUTH_CONNECTION.GOOGLE,
//   authConnectionId: "YOUR_INDIVIDUAL_GOOGLE_CONNECTION_ID",
//   groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
// });

// For Custom JWT login part of the group:
// const idToken = await getMyIdToken();
// await web3auth.connectTo(WALLET_CONNECTORS.AUTH, {
//   authConnection: AUTH_CONNECTION.CUSTOM,
//   idToken: idToken,
//   authConnectionId: "YOUR_INDIVIDUAL_CUSTOM_JWT_CONNECTION_ID",
//   groupedAuthConnectionId: "YOUR_GROUPED_CONNECTION_ID_FROM_DASHBOARD",
// });

You first create individual "Connections" on the dashboard for each auth provider (e.g., one for Google, one for your custom JWT). Then, you create a "Grouped Connection" on the dashboard, selecting the individual connections you want to group.

Action​

  1. Your existing v7 Aggregate Verifiers (and their sub-verifiers) will be automatically migrated to the new v10 dashboard. They will appear as individual "Connections" that are part of a "Grouped Connection".
  2. On the v10 dashboard, locate your migrated Grouped Connection. Note its groupedAuthConnectionId.
  3. For each login method within that group, find the corresponding individual migrated Connection and note its specific authConnectionId.
  4. Update your v10 client code to use both the groupedAuthConnectionId (for the group) and the specific authConnectionId (for the particular login method being invoked) in modalConfig or connectTo calls. The v7 verifierSubIdentifier is no longer used in the client.

Summary​

This dashboard-centric approach, with automatic migration of existing verifiers, simplifies client-side logic and provides a more robust way to manage authentication methods.

Next Steps​

Return to the main v7 to v10 migration guide to continue with other migration aspects like method name changes and initialization updates.