> For the complete documentation index, see [llms.txt](/llms.txt).

# 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](https://web3auth.io/pricing.html) 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[​](#getting-an-auth-connection-id "Direct link to Getting an auth connection ID")

prerequisite

To enable this, [create a connection](/embedded-wallets/dashboard/authentication/) from the **Authentication** tab of your project in the [Embedded Wallets developer dashboard](https://developer.metamask.io) 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](/embedded-wallets/authentication/) and the different configurations available for each connection.

## Configuration[​](#configuration "Direct link to 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](https://web3auth.io/pricing.html) 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[​](#parameters "Direct link to Parameters")

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

- Table
- Class

| Parameter                | Description                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| authConnection           | Type of sign-in for the connection. For example, google for Google OAuth or custom for JWT. Mandatory.         |
| authConnectionId         | Auth connection ID registered in the Embedded Wallets dashboard. Mandatory.                                    |
| clientId                 | Client 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.                                                                      |

```
class AuthConnectionConfig {
  final AuthConnection authConnection;
  final String authConnectionId;
  final String clientId;
  final String? name;
  final String? description;
  final String? groupedAuthConnectionId;
  final String? logoHover;
  final String? logoLight;
  final String? logoDark;
  final bool? mainOption;
  final bool? showOnModal;
  final bool? showOnDesktop;
  final bool? showOnMobile;
  final ExtraLoginOptions? jwtParameters;

  AuthConnectionConfig({
    required this.authConnection,
    required this.authConnectionId,
    required this.clientId,
    this.name,
    this.description,
    this.groupedAuthConnectionId,
    this.logoHover,
    this.logoLight,
    this.logoDark,
    this.mainOption,
    this.showOnModal,
    this.showOnDesktop,
    this.showOnMobile,
    this.jwtParameters,
  });
}

```

### Usage[​](#usage "Direct link to Usage")

- Google
- Firebase JWT
- Auth0

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

```

Usage

```
Future<void> initWeb3Auth() async {
  final authConnectionConfig = [
    AuthConnectionConfig(
      authConnection: AuthConnection.custom,
      authConnectionId: "w3a-firebase-demo",
      clientId: "WEB3AUTH_CLIENT_ID",
    ),
  ];

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

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

// Obtain a Firebase ID token from your auth provider, then:
final Web3AuthResponse response = await Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.custom,
    authConnectionId: "w3a-firebase-demo",
    idToken: firebaseIdToken,
  ),
);

```

Usage

```
Future<void> initWeb3Auth() async {
  final authConnectionConfig = [
    AuthConnectionConfig(
      authConnection: AuthConnection.custom,
      authConnectionId: "w3a-auth0-demo",
      clientId: "YOUR_AUTH0_CLIENT_ID",
    ),
  ];

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

  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.custom,
    authConnectionId: "w3a-auth0-demo",
    extraLoginOptions: ExtraLoginOptions(
      domain: "https://tenant-name.us.auth0.com",
      userIdField: "sub",
    ),
  ),
);

```

## Configure extra login options[​](#configure-extra-login-options "Direct link to 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[​](#parameters-1 "Direct link to Parameters")

| Parameter              | Description                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 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[​](#email-and-sms-passwordless "Direct link to 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[​](#grouped-connections "Direct link to 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](/embedded-wallets/authentication/group-connections/) for dashboard setup.