Skip to main content

Using Custom Authentication

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.

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, you need to create a connection from the Authentication tab of your project from the Embedded Wallets developer dashboard with your desired configuration.

To configure a connection, you need to provide the particular details of the connection into our Embedded Wallets dashboard. This enables us to map a authConnectionId with your connection details. This authConnectionId helps us to identify the connection details while initializing the SDK. You can configure multiple connections for the same project, and you can also update the connection details anytime.

tip

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

Configuration​

warning

"Auth Connection" is called "Verifier" in the Android SDK. It is the older terminology which we will be updating in the upcoming releases.

Consequentially, you will see the terms "Verifier ID" and "Aggregate Verifier" used in the codebase and documentation referring to "Auth Connection ID" and "Grouped Auth Connection" respectively.

To use custom authentication (using supported Social providers or Login providers like Auth0, AWS Cognito, Firebase, or your own custom JWT login), you can add the configuration using loginConfig parameter during the initialization.

The loginConfig parameter is a key value map. The key should be one of the Web3AuthProvider in its string form, and the value should be a LoginConfigItem instance.

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 verifier, you can use the following parameters in the LoginConfigItem.

ParameterDescription
verifierThe name of the verifier that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and it accepts a string value.
typeOfLoginType of login of this verifier, this value will affect the login flow that is adapted. For example, if you choose google, a Google sign-in flow will be used. If you choose jwt, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts TypeOfLogin as a value.
clientIdClient ID provided by your login provider used for custom verifier. for example, Google's Client ID or Web3Auth's client ID if using JWT as TypeOfLogin. It's a mandatory field, and it accepts a string value.
name?Display name for the verifier. If null, the default name is used. It accepts a string value.
description?Description for the button. If provided, it renders as a full length button. else, icon button. It accepts a string value.
verifierSubIdentifier?The field in JWT token which maps to verifier ID. Ensure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value.
logoHover?Logo to be shown on mouse hover. It accepts a string value.
logoLight?Light logo for dark background. It accepts a string value.
logoDark?Dark logo for light background. It accepts a string value.
mainOption?Show login button on the main list. It accepts a boolean value.
showOnModal?Whether to show the login button on modal or not.
showOnDesktop?Whether to show the login button on desktop.
showOnMobile?Whether to show the login button on mobile.

Usage​

Usage
Future<void> initWeb3Auth() async {
  final themeMap = HashMap<String, String>();
  themeMap['primary'] = "#229954";

  final loginConfig = new HashMap<String, LoginConfigItem>();
  loginConfig['google'] = LoginConfigItem(
    verifier: "verifier-name", // get it from Embedded Wallets/Web3Auth dashboard
    typeOfLogin: TypeOfLogin.google,
    clientId: "google_client_id" // Google's client ID
  );

  Uri redirectUrl;
  if (Platform.isAndroid) {
    redirectUrl = Uri.parse('{SCHEME}://{HOST}/auth');
    // w3a://com.example.w3aflutter/auth
  } else if (Platform.isIOS) {
    redirectUrl = Uri.parse('{bundleId}://auth');
    // com.example.w3aflutter://openlogin
  } else {
    throw UnKnownException('Unknown platform');
  }

  await Web3AuthFlutter.init(
    Web3AuthOptions(
      clientId: "WEB3AUTH_CLIENT_ID",
      network: Network.sapphire_mainnet,
      redirectUrl: redirectUrl,
      loginConfig: loginConfig
    ),
  );
}

// Login
final Web3AuthResponse response = await Web3AuthFlutter.login(
  LoginParams(loginProvider: Provider.google)
);

Congfigure extra login options​

Additional to the loginConfig during initialization, you can pass extra options to the login method to configure the login flow for cases requiring additional info for authorization. The ExtraLoginOptions accepts the following parameters.

Parameters​

ParameterDescription
additionalParams?Additional params in Map format for OAuth login, use id_token(JWT) to authenticate with Web3Auth.
domain?Your custom authentication domain in String format. For example, if you are using Auth0, it can be example.au.auth0.com.
client_id?Client ID in string format, provided by your login provider used for custom verifier.
leeway?The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It accepts a string value.
verifierIdField?The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value.
isVerifierIdCaseSensitive?Boolean to confirm Whether the verifier ID field is case sensitive or not.
display?Allows developers the configure the display of UI. It takes Display as a value.
prompt?Prompt shown to the user during authentication process. It takes Prompt as a value.
max_age?Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value.
ui_locales?The space separated list of language tags, ordered by preference. For instance fr-CA fr en.
id_token_hint?It denotes the previously issued ID token. It accepts a string value.
id_token?JWT (ID token) to be passed for login.
login_hint?It is used to send the user's email address during email passwordless login. It accepts a string value.
acr_values?acc_values
scope?The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It accepts a string value.
audience?The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It accepts a string value.
connection?The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It accepts a string value.
state?state
response_type?Defines which grant to execute for the authorization server. It accepts a string value.
nonce?nonce
redirect_uri?It can be used to specify the default URL, where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application.

Single verifer example​

Auth0 has a special login flow, called the SPA flow. This flow requires a client_id and domain to be passed, and Web3Auth will get the JWT id_token from Auth0 directly. You can pass these configurations in the ExtraLoginOptions object in the login function.

Future<void> initWeb3Auth() async {
  final themeMap = HashMap<String, String>();
  themeMap['primary'] = "#229954";

  final loginConfig = new HashMap<String, LoginConfigItem>();
  loginConfig['jwt'] = LoginConfigItem(
    verifier: "verifier-name", // get it from Embedded Wallets/Web3Auth dashboard for auth0 configuration
    typeOfLogin: TypeOfLogin.jwt,
    clientId: "auth0_client_id" // get it from auth0 dashboard
  );

  Uri redirectUrl;
  if (Platform.isAndroid) {
    redirectUrl = Uri.parse('{SCHEME}://{HOST}/auth');
    // w3a://com.example.w3aflutter/auth
  } else if (Platform.isIOS) {
    redirectUrl = Uri.parse('{bundleId}://auth');
    // com.example.w3aflutter://openlogin
  } else {
    throw UnKnownException('Unknown platform');
  }

  await Web3AuthFlutter.init(
    Web3AuthOptions(
      clientId: "WEB3AUTH_CLIENT_ID",
      network: Network.sapphire_mainnet,
      redirectUrl: redirectUrl,
      loginConfig: loginConfig,
    ),
  );
}

// Login
final Web3AuthResponse response = await Web3AuthFlutter.login(
  LoginParams(
    loginProvider: Provider.jwt,
    extraLoginOptions: ExtraLoginOptions(
      domain: "https://tenant-name.us.auth0.com", // Domain of your auth0 app
      verifierIdField: "sub", // The field in JWT token which maps to verifier ID.
    )
  )
);

Aggregate verifier example​

You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and email passwordless login, or Google and GitHub via Auth0 to access the same address for your user.

final loginConfig = HashMap<String, LoginConfigItem>();

loginConfig['google'] = LoginConfigItem(
  verifier: "aggregate-sapphire",
  verifierSubIdentifier: "w3a-google",
  typeOfLogin: TypeOfLogin.google,
  clientId: "YOUR_GOOGLE_CLIENT_ID",
);

loginConfig['jwt'] = LoginConfigItem(
  verifier: "aggregate-sapphire",
  verifierSubIdentifier: "w3a-a0-github",
  typeOfLogin: TypeOfLogin.jwt,
  clientId: "YOUR_AUTHO_CLIENT_ID",
);

await Web3AuthFlutter.init(
  Web3AuthOptions(
    clientId: 'YOUR_WEB3AUTH_CLIENT_ID',
    network: Network.sapphire_mainnet,
    redirectUrl: redirectUrl,
    loginConfig: loginConfig,
  ),
);

await Web3AuthFlutter.initialize();

// Login with Google
await Web3AuthFlutter.login(LoginParams(loginProvider: Provider.google));

// Login With GitHub
await Web3AuthFlutter.login(
  LoginParams(
    loginProvider: Provider.jwt,
    extraLoginOptions: ExtraLoginOptions(
      domain: 'https://web3auth.au.auth0.com',
      verifierIdField: 'email',
      connection: 'github',
      isVerifierIdCaseSensitive: false,
    ),
  ),
);
On this page