Group Connections

Group Connections enable multiple login methods to be linked to the same on-chain user identity. This means that users logging in with different authentication providers (e.g., Google and Email Passwordless) can still access the same wallet address—ensuring a unified user experience.

Before setting up a group connection, developers must first configure individual login connections that are eligible.

Set Up a Group Connection

Create Group Connection on Dashboard

To use this feature, developers must go to the Group Connections tab in the Web3Auth Dashboard.

Follow these steps:

1. Visit the Web3Auth Dashboard.
2. Go to the Group Connections section.
3. Click on the Create Group button.
4. Enter your custom Group Name.
5. Select 1st social connection and 2nd social connection.
6. Click Create Group.

Usage

Since, the Group Connections details are available from Dashboard, developers don't need to pass any additional parameters to the Web3AuthProvider.

Follow our Quickstart Guide to setup the basic flow.

Modal Connection

web3authContext.tsx

import { WALLET_CONNECTORS, WEB3AUTH_NETWORK } from "@web3auth/modal";
import { type Web3AuthContextConfig } from "@web3auth/modal/react";

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId: "YOUR_CLIENT_ID",
    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    modalConfig: {
      connectors: {
        [WALLET_CONNECTORS.AUTH]: {
          label: "auth",
          loginMethods: {
            google: {
              name: "google login",
              authConnectionId: "w3a-google",
              groupedAuthConnectionId: "aggregate-sapphire",
            },
            facebook: {
              name: "facebook login",
              authConnectionId: "w3a-facebook",
              groupedAuthConnectionId: "aggregate-sapphire",
            },
            email_passwordless: {
              name: "email passwordless login",
              authConnectionId: "w3a-email-passwordless",
              groupedAuthConnectionId: "aggregate-sapphire",
            },
          },
        },
      },
    },
  },
};

export default web3AuthContextConfig;

Google [Implicit] + Auth0 [Implicit]

App.tsx

const loginWithGoogle = async () => {
  await connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-google",
    authConnection: AUTH_CONNECTION.GOOGLE,
  });
};

const loginWithAuth0Google = async () => {
  await connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-a0-google",
    authConnection: AUTH_CONNECTION.CUSTOM,
    extraLoginOptions: {
      connection: "google-oauth2",
    },
  });
};

const loginWithAuth0GitHub = async () => {
  await connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-a0-github",
    authConnection: AUTH_CONNECTION.CUSTOM,
    extraLoginOptions: {
      connection: "github",
    },
  });
};

Google One Tap [JWT] + Auth0 [JWT]

App.tsx

const loginWithGoogle = async (response: CredentialResponse) => {
  const idToken = response.credential;

  await connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-google",
    authConnection: AUTH_CONNECTION.GOOGLE,
    idToken,
    extraLoginOptions: {
      isUserIdCaseSensitive: false,
      verifierIdField: "email",
    },
  });
};

const loginWithAuth0 = async () => {
  try {
    await loginWithPopup();
    const idToken = (await getIdTokenClaims())?.__raw.toString();
    if (!idToken) {
      throw new Error("No id token found");
    }

    await connectTo(WALLET_CONNECTORS.AUTH, {
      groupedAuthConnectionId: "aggregate-sapphire",
      authConnectionId: "w3a-a0-github",
      authConnection: AUTH_CONNECTION.CUSTOM,
      idToken,
      extraLoginOptions: {
        isUserIdCaseSensitive: false,
        verifierIdField: "email",
      },
    });
  } catch (err) {
    console.error(err);
  }
};

Google [Implicit] + Firebase [JWT]

App.tsx

const loginWithGoogle = async () => {
  await connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-google",
    authConnection: AUTH_CONNECTION.GOOGLE,
  });
};

const loginWithFirebaseGithub = async () => {
  const app = initializeApp(firebaseConfig);
  const auth = getAuth(app);
  const githubProvider = new GithubAuthProvider();

  const result = await signInWithPopup(auth, githubProvider);

  const idToken = await result.user.getIdToken(true);

  connectTo(WALLET_CONNECTORS.AUTH, {
    groupedAuthConnectionId: "aggregate-sapphire",
    authConnectionId: "w3a-firebase",
    authConnection: AUTH_CONNECTION.CUSTOM,
    idToken,
    extraLoginOptions: {
      isUserIdCaseSensitive: false,
    },
  });
};

Common Questions

The following questions can be answered using the information on this page:

1. What are Group Connections in Web3Auth?
2. How do Group Connections help users with multiple login methods?
3. How do I set up a Group Connection in Web3Auth?
4. What are the prerequisites for creating a Group Connection?
5. Can I link different authentication providers to the same wallet?
6. How do I create a Group Connection in the Web3Auth Dashboard?
7. What types of authentication providers can be grouped together?
8. Do I need to pass special parameters when using Group Connections?
9. How does Group Connections ensure a unified user experience?
10. What are some examples of Group Connection implementations?