> 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

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

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

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

**Table**

| 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**

```dart
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

**Google**

Usage

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

```

**Firebase JWT**

Usage

```dart
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://auth';
  }

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

```

**Auth0**

Usage

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

```

## 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

| 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

```dart
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:

```dart
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.