For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Using custom authentication

Custom authentication lets users sign in with your own OAuth provider or JWT issuer. For example, you can use your own Google Client ID, Firebase ID token, or Auth0 application.

This feature, with MFA turned off, can make Embedded Wallets invisible to the end user.

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.

Getting an auth connection ID​

prerequisite

To enable this, create a connection from the Authentication tab of your project in the Embedded Wallets developer dashboard with your desired configuration.

To configure a connection, provide the connection details in the Embedded Wallets dashboard. This maps an authConnectionId to your connection configuration. You can configure multiple connections for the same project and update connection details at any time.

tip

Learn more about the auth provider setup and the different configurations available for each connection.

Configuration​

To use custom authentication (social providers, Auth0, AWS Cognito, Firebase, or your own JWT login), add authConnectionConfig during initialization.

authConnectionConfig is a list of AuthConnectionConfig objects.

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.

Parameters​

After creating the connection, use the following parameters in AuthConnectionConfig.

ParameterDescription
authConnectionType of sign-in for the connection. For example, google for Google OAuth or custom for JWT. Mandatory.
authConnectionIdAuth connection ID registered in the Embedded Wallets dashboard. Mandatory.
clientIdClient ID from your login provider. Mandatory.
name?Display name for the connection. If null, the default name is used.
description?Description for the button. If provided, renders as a full-length button; otherwise, an icon button.
groupedAuthConnectionId?Grouped auth connection ID. If provided, authConnectionId becomes a sub-identifier for the grouped connection.
logoHover?Logo shown on mouse hover.
logoLight?Light logo for dark backgrounds.
logoDark?Dark logo for light backgrounds.
mainOption?Show the sign-in button on the main list.
showOnModal?Whether to show the sign-in button on the modal.
showOnDesktop?Whether to show the sign-in button on desktop.
showOnMobile?Whether to show the sign-in button on mobile.
jwtParameters?Extra JWT options for custom connections.

Usage​

Usage
Future<void> initWeb3Auth() async {
  final authConnectionConfig = [
    AuthConnectionConfig(
      authConnection: AuthConnection.google,
      authConnectionId: "YOUR_AUTH_CONNECTION_ID",
      clientId: "YOUR_GOOGLE_CLIENT_ID",
    ),
  ];

  late final String redirectUrl;
  if (Platform.isAndroid) {
    redirectUrl = 'w3a://com.example.w3aflutter';
  } else {
    redirectUrl = 'com.example.w3aflutter://auth';
  }

  await Web3AuthFlutter.init(
    Web3AuthOptions(
      clientId: "WEB3AUTH_CLIENT_ID",
      web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet,
      redirectUrl: redirectUrl,
      authConnectionConfig: authConnectionConfig,
    ),
  );
}

final Web3AuthResponse response = await Web3AuthFlutter.connectTo(
  LoginParams(authConnection: AuthConnection.google),
);

Configure extra login options​

In addition to authConnectionConfig during initialization, you can pass extra options to connectTo for authorization flows that need additional parameters. ExtraLoginOptions accepts the following parameters.

Parameters​

ParameterDescription
additionalParams?Additional params in Map format for OAuth sign-in.
domain?Your custom authentication domain. For example, example.au.auth0.com for Auth0.
client_id?Client ID provided by your login provider for custom connections.
leeway?Clock skew allowance for JWT expiration, in seconds. Ideally no more than 60–120 seconds.
userIdField?JWT field that maps to the user ID. Ensure you selected the correct JWT user identifier in the developer dashboard.
isUserIdCaseSensitive?Whether the user ID field is case sensitive.
display?Configures the display of the UI. Takes Display as a value.
prompt?Prompt shown during authentication. Takes Prompt as a value.
max_age?Max time allowed without reauthentication.
ui_locales?Space-separated list of language tags, ordered by preference. For instance fr-CA fr en.
id_token_hint?Previously issued ID token.
id_token?JWT (ID token) for legacy custom flows. Prefer LoginParams.idToken for Firebase and other JWT providers.
login_hint?User's email address for email passwordless sign-in.
flow_type?Email passwordless flow type. Defaults to EmailFlowType.code. Use EmailFlowType.link for magic-link flow.
redirect_uri?Default redirect URL for custom JWT verifiers. If you use Auth0, allowlist it in Allowed Callback URLs.

Email and SMS passwordless​

final Web3AuthResponse response = await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.email_passwordless,
    extraLoginOptions: ExtraLoginOptions(
      login_hint: "hello@web3auth.io",
    ),
  ),
);

For SMS passwordless, use the format +{country_code}-{phone_number} (for example, +91-9911223311).

Grouped connections​

Use grouped connections so the same user gets the same wallet address across multiple sign-in methods:

final authConnectionConfig = [
  AuthConnectionConfig(
    authConnection: AuthConnection.google,
    authConnectionId: "w3a-google",
    groupedAuthConnectionId: "aggregate-sapphire",
    clientId: "YOUR_GOOGLE_CLIENT_ID",
  ),
  AuthConnectionConfig(
    authConnection: AuthConnection.custom,
    authConnectionId: "w3a-a0-github",
    groupedAuthConnectionId: "aggregate-sapphire",
    clientId: "YOUR_AUTH0_CLIENT_ID",
  ),
];

await Web3AuthFlutter.init(
  Web3AuthOptions(
    clientId: "WEB3AUTH_CLIENT_ID",
    web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet,
    redirectUrl: redirectUrl,
    authConnectionConfig: authConnectionConfig,
  ),
);

// Sign in with Google
await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.google,
    authConnectionId: "w3a-google",
    groupedAuthConnectionId: "aggregate-sapphire",
  ),
);

// Sign in with GitHub via Auth0
await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.custom,
    authConnectionId: "w3a-a0-github",
    groupedAuthConnectionId: "aggregate-sapphire",
    extraLoginOptions: ExtraLoginOptions(
      domain: "https://web3auth.au.auth0.com",
      userIdField: "email",
      connection: "github",
      isUserIdCaseSensitive: false,
    ),
  ),
);

See grouped connections for dashboard setup.

On this page