# MetaMask Embedded Wallets SDKs
> Complete documentation for Embedded Wallets SDKs (React, Vue, JS, Node, Android, iOS, React Native, Flutter, Unity, Unreal)
This file contains all documentation content in a single document following the llmstxt.org standard.
## MetaMask Embedded Wallets
:::tip
Consider which sigining scheme your dapp requires before beginning your integration:
| SDK Family | Key Model | Available from |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [**Embedded Wallet SDKs**](/embedded-wallets/sdk/) | [SSS](/embedded-wallets/infrastructure/sss-architecture) (key reconstruction) | [Base, Growth, and Scale plans](https://web3auth.io/pricing.html) |
| **MPC Core Kit SDK** | [TSS/MPC](/embedded-wallets/infrastructure/mpc-architecture#threshold-signature-scheme-key) (no key reconstruction) | [Enterprise plan](https://web3auth.io/pricing.html) |
:::
---
## Embedded Wallets SDK for Android
## Overview
MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authentication for Android applications with social sign-in, external wallets, and more. Our Android SDK, written in Kotlin, simplifies how you connect users to their preferred wallets and manage authentication state natively.
## Requirements
- Android API version `26` or newer
- Android Compile and Target SDK: `34`
- Basic knowledge of Java or Kotlin development
## Prerequisites
- Set up your project on the [Embedded Wallets dashboard](https://developer.metamask.io/).
:::tip
See the [dashboard setup](../../dashboard/README.mdx) guide to learn more.
:::
## Installation
Install the Web3Auth Android SDK by adding it to your project dependencies:
### 1. Add JitPack repository
In your project-level Gradle file add JitPack repository:
```groovy
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// focus-next-line
maven { url "https://jitpack.io" } // <-- Add this line
}
}
```
### 2. Add Web3Auth dependency
Then, in your app-level `build.gradle` dependencies section, add the following:
```groovy
dependencies {
// ...
// focus-next-line
implementation 'com.github.web3auth:web3auth-android-sdk:10.0.1'
}
```
2.1. Update permissions
Open your app's `AndroidManifest.xml` file and add the following permission. Ensure the `` element is a direct child of the `` root element.
```xml
```
2.2 Configure `AndroidManifest.xml` File
Ensure your main activity `launchMode` is set to `singleTop` in your `AndroidManifest.xml`:
```xml
// ...
```
From version **7.1.2**, set `android:allowBackup` to `false` and add `tools:replace="android:fullBackupContent"` in your `AndroidManifest.xml` file:
```xml
```
### 3. Handle redirects
Once the Gradle files and permissions have been updated, you need to configure your Embedded Wallets project by allowlisting your scheme and package name.
#### Configure a Plug n Play project
- From the [Embedded Wallets dashboard](https://developer.metamask.io), create or open an existing Web3Auth project.
- Allowlist `{SCHEME}://{YOUR_APP_PACKAGE_NAME}` in the dashboard. This step is mandatory for the redirect to work.
#### Configure deep link
Open your app's `AndroidManifest.xml` file and add the following deep link intent filter to your main activity:
```xml
```
### 4. Triggering sign-in exceptions
:::note
The Android SDK uses the custom tabs and from current implementation of Chrome custom tab, it's not possible to add a listener directly to Chrome custom tab close button and trigger sign-in exceptions.
:::
Apply the `setCustomTabsClosed` method in your sign-in screen to trigger sign-in exceptions for Android.
```kotlin
class MainActivity : AppCompatActivity() {
// Additional code
override fun onResume() {
super.onResume()
// focus-start
if (Web3Auth.getCustomTabsClosed()) {
Toast.makeText(this, "User closed the browser.", Toast.LENGTH_SHORT).show()
web3Auth.setResultUrl(null)
Web3Auth.setCustomTabsClosed(false)
}
// focus-end
}
// Additional code
}
```
## Initialize Embedded Wallets
### 1. Create an Embedded Wallets instance
Create an Embedded Wallets instance and configure it with your project settings:
```kotlin
// focus-start
var web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
),
this
)
// focus-end
// Handle user signing in when app is in background
web3Auth.setResultUrl(intent?.data)
```
### 2. Set result URL
Whenever user initiates a sign-in flow, a new intent of CustomTabs is launched. It's necessary step to use `setResultUrl` in `onNewIntent` method to successful track the sign-in process.
```kotlin
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
// Handle user signing in when app is active
web3Auth.setResultUrl(intent.data)
}
```
### 3. Initialize the Embedded Wallets instance
After instantiating Embedded Wallets, the next step is to initialize it using the `initialize` method. This method is essential for setting up the SDK, checking for any active sessions, and fetching the whitelabel configuration from your dashboard.
Once the `initialize` method executes successfully, you can use the `getPrivateKey` or `getEd25519PrivateKey` methods to verify if an active session exists. If there is no active session, these methods will return an empty string; otherwise, they will return the respective private key.
:::note
The `initialize` method may throw an error in the following situations:
- No active session exists for the user.
- A network error occurs while fetching the project configuration from the dashboard.
- Session validation fails (for example, the stored session token is invalid or expired).
Wrap the call in a `whenComplete` handler and treat any non-null error as a failed initialization rather than an absent session.
:::
```kotlin
val initializeCF: CompletableFuture = web3Auth.initialize()
initializeCF.whenComplete { _, error ->
if (error == null) {
// Check for the active session
if(web3Auth.getPrivateKey().isNotEmpty()) {
// Active session found
}
// No active session is not present
} else {
// Handle the error
}
}
```
## Advanced configuration
The Web3Auth Android SDK offers a rich set of advanced configuration options:
- **[Custom authentication](./advanced/custom-authentication.mdx):** Define authentication methods.
- **[Whitelabeling and UI customization](./advanced/whitelabel.mdx):** Personalize the modal's appearance.
- **[Multi-Factor Authentication (MFA)](./advanced/mfa.mdx):** Set up and manage MFA.
- **[Dapp Share](./advanced/dapp-share.mdx):** Share dapp sessions across devices.
:::tip
See the [advanced configuration sections](./advanced/) to learn more about each configuration option.
:::
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_CLIENT_ID",
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET
redirectUrl = "YOUR_APP_SCHEME://auth"
),
this
)
```
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_CLIENT_ID",
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET
redirectUrl = "YOUR_APP_SCHEME://auth",
authConnectionConfig = listOf(AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.GOOGLE,
clientId = getString(R.string.google_client_id) // Google's client id
)),
mfaSettings = MfaSettings(
deviceShareFactor = MfaSetting(true, 1, true),
socialBackupFactor = MfaSetting(true, 2, true),
passwordFactor = MfaSetting(true, 3, false),
backUpShareFactor = MfaSetting(true, 4, false),
passkeysFactor = MfaSetting(true, 5, true),
authenticatorFactor = MfaSetting(true, 6, true),
)
),
this
)
```
## Single Factor Auth (SFA) Support
Web3Auth Android SDK includes built-in support for Single Factor Auth (SFA), allowing for seamless authentication when you already have a JWT token from your authentication system. When MFA is disabled, users won't even notice Web3Auth's presence; they'll be automatically authenticated using just your JWT token, making the sign-in experience frictionless.
```kotlin
// SFA sign-in with custom JWT
val loginCompletableFuture = web3Auth.connectTo(
LoginParams(
AuthConnection.CUSTOM,
authConnectionId = "your_verifier_id",
idToken = "your_jwt_token"
)
)
```
SFA mode is automatically activated when you provide an `idToken` parameter. This enables direct authentication without additional social sign-in steps, perfect for applications that already have their own authentication system.
## Blockchain Integration
Embedded Wallets is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Embedded Wallets offers robust support for both **Solana** and **Ethereum**.
### Ethereum integration
For Ethereum integration, you can get the private key using the `getPrivateKey` method and use it with web3j or other Ethereum libraries:
```kotlin
// Use your Web3Auth instance to get the private key
val privateKey = web3Auth.getPrivateKey()
// Generate the Credentials
val credentials = Credentials.create(privateKey)
// Get the address
val address = credentials.address
// Create the Web3j instance using your RPC URL
val web3 = Web3j.build(HttpService("YOUR_RPC_URL"))
// Get the balance
val balanceResponse = web3.ethGetBalance(address, DefaultBlockParameterName.LATEST).send()
// Convert the balance from Wei to Ether format
val ethBalance = BigDecimal.valueOf(balanceResponse.balance.toDouble()).divide(BigDecimal.TEN.pow(18))
```
### Solana integration
For Solana integration, you can get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with sol4k or any other Solana libraries:
```kotlin
val connection = Connection(RpcUrl.DEVNET)
// Use your Web3Auth instance to get the private key
val ed25519PrivateKey = web3Auth.getEd25519PrivateKey()
// Generate the Solana KeyPair
val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray())
// Get the user's public key
val publicKey = solanaKeyPair.publicKey.toBase58()
// Get the user balance
val userBalance = connection.getBalance(publicKey).toBigDecimal()
```
---
## Advanced configuration
The Embedded Wallets SDK provides extensive configuration options that allow you to customize authentication flows, UI appearance, blockchain integrations, and security features to meet your application's specific requirements.
## Configuration structure
When setting up Embedded Wallets, you'll pass in the options to the constructor. This consists of:
```kotlin
// focus-start
var web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
),
this
)
// focus-end
// Handle user signing in when app is in background
web3Auth.setResultUrl(intent?.data)
```
### `Web3AuthOptions`
The Web3Auth Constructor takes an object with `Web3AuthOptions` as input.
| Parameter | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context` | Android context to launch web-based authentication, usually is the current activity. It's a mandatory field, and accepts `android.content.Context` as a value. |
| `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` |
| `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. |
| `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. |
| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is `86400 * 30` (30 days). `sessionTime` can be max 30 days. |
| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for pre-generated wallets and SFA mode. |
| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. |
| `defaultChainId?` | Default chain ID to use. It's an optional field with a default value of `"0x1"` (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. |
| `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. |
| Parameter | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `whiteLabel?` | Whitelabel options for Embedded Wallets. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. |
| `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. |
| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. |
| `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. It takes `WalletServicesConfig` as a value. |
```kotlin
data class Web3AuthOptions(
val clientId: String,
var redirectUrl: String,
@SerializedName("network") val web3AuthNetwork: Web3AuthNetwork,
@SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION,
var whiteLabel: WhiteLabelData? = null,
var authConnectionConfig: List? = emptyList(),
val useSFAKey: Boolean? = false,
var chains: Chains? = null,
var mfaSettings: MfaSettings? = null,
val sessionTime: Int = 30 * 86400,
val walletServicesConfig: WalletServicesConfig? = null,
var defaultChainId: String? = "0x1",
var enableLogging: Boolean = false
)
```
## Session management
Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keystore.
**Key Configuration Options:**
- `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again.
- Minimum: 1 second (`1`).
- Maximum: 30 days (`86400 * 30`).
- Default: 30 days (`86400 * 30`).
```kotlin
var web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
sessionTime = 86400 * 7, // 7 days (in seconds)
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
),
this
)
```
## Chains Configuration
The `chains` parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by Wallet Services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard.
### `Chains` Fields
| Field | Type | Required | Description |
| ------------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `chainId` | `String` | Yes | Chain ID in hex format (for example, `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). |
| `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. |
| `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. |
| `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. |
| `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. |
| `displayName` | `String?` | No | Human-readable name for the chain. |
| `logo` | `String?` | No | URL of the chain's logo image. |
| `ticker` | `String?` | No | Ticker symbol for the native token (for example, `"ETH"`). |
| `tickerName` | `String?` | No | Full name of the native token (for example, `"Ethereum"`). |
### Interface
```kotlin
data class Chains(
val chainNamespace: ChainNamespace = ChainNamespace.EIP155,
val decimals: Int? = 18,
val blockExplorerUrl: String? = null,
val chainId: String,
val displayName: String? = null,
val logo: String? = null,
val rpcTarget: String,
val ticker: String? = null,
val tickerName: String? = null,
)
```
### Example
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID",
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "YOUR_APP_SCHEME://auth",
chains = Chains(
chainId = "0x89",
rpcTarget = "https://rpc.ankr.com/polygon",
displayName = "Polygon Mainnet",
ticker = "MATIC",
tickerName = "Matic",
blockExplorerUrl = "https://polygonscan.com"
)
),
this
)
```
## Custom authentication methods
Control the sign-in options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](./custom-authentication.mdx) section.
## UI customization
Customize the brand experience by customizing the Embedded Wallets sign-in screens to match your application's design. For complete customization options, refer to the [Whitelabeling & UI Customization](./whitelabel.mdx) section.
## Multi-Factor Authentication
Add additional security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see the [Multi-Factor Authentication](./mfa.mdx) section.
**Key Configuration Options:**
- `mfaSettings` - Configure MFA settings for different authentication flows
- `mfaLevel` - Control when users are prompted to set up MFA
## Wallet Services Configuration
The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customize the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Smart Accounts](./smart-accounts) section.
| Parameter | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `ConfirmationStrategy.DEFAULT`. |
| `whiteLabel?` | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. |
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID",
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "YOUR_APP_SCHEME://auth",
walletServicesConfig = WalletServicesConfig(
confirmationStrategy = ConfirmationStrategy.MODAL
)
),
this
)
```
---
## 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 Multi-Factor Authentication (MFA) turned off, can even 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
:::info prerequisite
To enable this, you need to [create a connection](/embedded-wallets/dashboard/authentication) from the **Authentication** tab of your project from the [Embedded Wallets dashboard](https://developer.metamask.io) with your desired configuration.
:::
To configure a connection, you need to provide the particular details of the connection in the 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](/embedded-wallets/authentication) and the different configurations available for each connection.
:::
## Configuration
To use custom authentication (using social providers or sign-in providers like Auth0, AWS identity services, Firebase, and so on, or even your own custom JWT sign-in) you can add the configuration using `authConnectionConfig` parameter during the initialization.
**"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.
The `authConnectionConfig` parameter is a list of `AuthConnectionConfig` instances, each defining a specific authentication connection.
After creating the auth connection from the [Web3Auth Dashboard](https://dashboard.web3auth.io), you can use the following parameters in the `AuthConnectionConfig`.
| Parameter | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authConnectionId` | The name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a value. |
| `authConnection` | Type of sign-in for this auth connection; this value affects the sign-in flow that is used. For example, if you choose the Google auth connection, a Google sign-in flow will be used. If you choose `custom`, you should be providing your own JWT token, and no sign-in flow will be presented. It's a mandatory field, and accepts `AuthConnection` as a value. |
| `clientId` | Client id provided by your sign-in provider used for custom auth connection. For example, Google's Client ID or Web3Auth's client Id if using `custom` as AuthConnection. It's a mandatory field, and accepts `String` as a value. |
| `name?` | Display name for the auth connection. If null, the default name is used. It accepts `String` as a value. |
| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts `String` as a value. |
| `groupedAuthConnectionId?` | The field in JWT token which maps to the grouped Auth Connection ID. Please make sure you selected the correct JWT Auth Connection ID in the developer dashboard. It accepts `String` as a value. |
| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. |
| `logoLight?` | Light logo for dark background. It accepts `String` as a value. |
| `logoDark?` | Dark logo for light background. It accepts `String` as a value. |
| `mainOption?` | Show sign-in button on the main list. It accepts `Boolean` as a value. Default value is false. |
| `showOnModal?` | Whether to show the sign-in button on modal or not. Default value is true. |
| `showOnDesktop?` | Whether to show the sign-in button on desktop. Default value is true. |
| `showOnMobile?` | Whether to show the sign-in button on mobile. Default value is true. |
```kotlin
data class AuthConnectionConfig(
var authConnectionId: String,
private var authConnection: AuthConnection,
private var name: String? = null,
private var description: String? = null,
private var clientId: String,
private var groupedAuthConnectionId: String? = null,
private var logoHover: String? = null,
private var logoLight: String? = null,
private var logoDark: String? = null,
private var mainOption: Boolean? = false,
private var showOnModal: Boolean? = true,
private var showOnDesktop: Boolean? = true,
private var showOnMobile: Boolean? = true,
)
enum class AuthConnection {
@SerializedName("google")
GOOGLE,
@SerializedName("facebook")
FACEBOOK,
@SerializedName("reddit")
REDDIT,
@SerializedName("discord")
DISCORD,
@SerializedName("twitch")
TWITCH,
@SerializedName("apple")
APPLE,
@SerializedName("line")
LINE,
@SerializedName("github")
GITHUB,
@SerializedName("kakao")
KAKAO,
@SerializedName("linkedin")
LINKEDIN,
@SerializedName("twitter")
TWITTER,
@SerializedName("weibo")
WEIBO,
@SerializedName("wechat")
WECHAT,
@SerializedName("email_passwordless")
EMAIL_PASSWORDLESS,
@SerializedName("custom")
CUSTOM, // for jwt
@SerializedName("sms_passwordless")
SMS_PASSWORDLESS,
@SerializedName("farcaster")
FARCASTER
}
```
### Usage
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.GOOGLE,
clientId = getString(R.string.google_client_id) // Google's client id
))
// focus-end
),
this
)
// focus-start
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(AuthConnection.GOOGLE)
)
// focus-end
```
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(
AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.FACEBOOK,
clientId = getString(R.string.facebook_client_id) // Facebook's client id
)
)
// focus-end
),
this
)
// focus-start
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(AuthConnection.FACEBOOK)
)
// focus-end
```
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.CUSTOM,
clientId = getString(R.string.auth0_project_id) // Auth0's client id
))
// focus-end
),
this
)
// focus-start
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(AuthConnection.CUSTOM)
)
// focus-end
```
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(
AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.CUSTOM,
)
)
// focus-end
),
this
)
// focus-start
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(AuthConnection.CUSTOM)
)
// focus-end
```
## Configure extra sign-in options
Additional to the `LoginConfig` you can pass extra options to the `connectTo` method to configure the sign-in flow for cases requiring additional info for enabling sign-in. The `ExtraLoginOptions` accepts the following parameters.
### Parameters
| Parameter | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `additionalParams?` | Additional params in `HashMap` format for OAuth sign-in, 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 sign-in provider used for custom verifier. |
| `leeway?` | The value used to account for clock skew in JWT expiration times. The value is in seconds, and ideally should be no more than 60 seconds or 120 seconds at max. It takes `String` as a value. |
| `userIdField?` | The field in JWT token which maps to user id. Please make sure you selected correct JWT user id in the developer dashboard. It takes `String` as a value. |
| `isUserIdCaseSensitive?` | Boolean to confirm Whether the user 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 re-authentication. If the last time the user authenticated is greater than this value, then the user must re-authenticate. It takes `String` as a 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 takes `String` as a value. |
| `id_token?` | JWT (ID Token) to be passed for sign-in. |
| `access_token?` | Access token for OAuth flows. It takes `String` as a value. |
| `flow_type?` | Specifies the email passwordless flow type. It takes `EmailFlowType` as a value (`CODE` or `LINK`). |
| `acr_values?` | Authentication Context Class Reference values for the authorization request. |
| `scope?` | The default scope to be used on authentication requests. The default scope defined in the Auth0 client is included along with this scope. It takes `String` as a value. |
| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. |
| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 sign-in page and show the Auth0 sign-in widget. It takes `String` as a value. |
| `state?` | state |
| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a 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 allowlisted in the Allowed Callback URLs in your Auth0 application. |
```kotlin
data class ExtraLoginOptions(
private var additionalParams : HashMap? = null,
private var domain : String? = null,
private var client_id : String? = null,
private var leeway : String? = null,
private var userIdField : String? = null,
private var isUserIdCaseSensitive : Boolean? = null,
private var display : Display? = null,
private var prompt : Prompt? = null,
private var max_age : String? = null,
private var ui_locales : String? = null,
private var id_token : String? = null,
private var id_token_hint : String? = null,
private var access_token : String? = null,
private var flow_type : EmailFlowType? = null,
private var acr_values : String? = null,
private var scope : String? = null,
private var audience : String? = null,
private var connection : String? = null,
private var state : String? = null,
private var response_type : String? = null,
private var nonce : String? = null,
private var redirect_uri : String? = null
)
enum class EmailFlowType {
@SerializedName("code")
CODE,
@SerializedName("link")
LINK
}
```
### Single verifier Usage
Auth0 has a special sign-in 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 `connectTo` method.
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.CUSTOM,
clientId = getString(R.string.auth0_project_id) // Auth0's client id
))
// focus-end
),
this
)
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(
AuthConnection.CUSTOM,
// focus-start
extraLoginOptions = ExtraLoginOptions(
domain = "https://username.us.auth0.com", // Domain of your Auth0 app
userIdField = "sub", // The field in jwt token which maps to user id.
)
// focus-end
)
)
```
If you're using any other provider like Firebase, AWS identity services, or deploying your own custom JWT
server, you need to put the jwt token into the `idToken` field of the `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional sign-in flows.
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(AuthConnectionConfig(
authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard
authConnection = AuthConnection.CUSTOM,
))
// focus-end
),
this
)
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(
AuthConnection.CUSTOM,
// focus-start
idToken = "Your JWT id token",
// focus-end
)
)
```
To use the Email Passwordless sign-in, you need to put the email into the `loginHint` parameter of
the `LoginParams`. By default, the sign-in flow will be `code` flow, if you want to use the
`link` flow, you need to put `flow_type` into the `extraLoginOptions` parameter.
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
),
this
)
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(
AuthConnection.EMAIL_PASSWORDLESS,
// focus-start
loginHint = "hello@web3auth.io",
extraLoginOptions = ExtraLoginOptions(
flow_type = EmailFlowType.CODE // Use CODE for OTP flow or LINK for magic link flow
)
// focus-end
)
)
```
To use the SMS Passwordless sign-in, send the phone number as the `loginHint` parameter of the
`LoginParams`. Please make sure the phone number is in the format of
+\{country_code}-\{phone_number}, that is, (+91-09xx901xx1).
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
),
this
)
// focus-start
val loginCompletableFuture: CompletableFuture = web3Auth.connectTo(
LoginParams(
AuthConnection.SMS_PASSWORDLESS,
loginHint = "+91-9911223344"
)
)
// focus-end
```
### Grouped Auth Connection Usage
You can use grouped auth connections to combine multiple sign-in methods to get the same address for the users regardless of their sign-in providers. For example, combining a Google and Email Passwordless sign-in, or Google and GitHub via Auth0 to access the same address for your user.
```kotlin
val web3Auth = Web3Auth(
Web3AuthOptions(
clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
// focus-start
authConnectionConfig = listOf(
AuthConnectionConfig(
authConnectionId = "aggregate-sapphire",
groupedAuthConnectionId = "w3a-google",
authConnection = AuthConnection.GOOGLE,
name = "Aggregate Login",
clientId = getString(R.string.web3auth_google_client_id)
),
AuthConnectionConfig(
authConnectionId = "aggregate-sapphire",
groupedAuthConnectionId = "w3a-a0-email-passwordless",
authConnection = AuthConnection.CUSTOM,
name = "Aggregate Login",
clientId = getString(R.string.web3auth_auth0_client_id)
)
)
// focus-end
),
this
)
// focus-start
// Google Login
web3Auth.connectTo(LoginParams(AuthConnection.GOOGLE))
// focus-end
// focus-start
// Auth0 Login
web3Auth.connectTo(LoginParams(
AuthConnection.CUSTOM,
extraLoginOptions = ExtraLoginOptions(
domain = "https://web3auth.au.auth0.com",
userIdField = "email",
isUserIdCaseSensitive = false
)
))
// focus-end
```
---
## Dapp share
## Embedded Wallets infrastructure at a glance
As described in the [Embedded Wallets infrastructure](/embedded-wallets/infrastructure/), to enable non-custodial key management in Embedded Wallets, we split the private key into multiple parts, that is, into `shares`. These shares are a part of the offchain multisig, where multiple shares are stored in different places and can be used to reconstruct the private key dynamically in the user's frontend application. Typically, there are 3 shares:
1. **`ShareA` is managed by a sign-in service via node operators:** This share is further split amongst a network of nodes and retrieved via conventional authentication flows.
2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics.
3. **`ShareC` is a recovery share:** An extra share to be kept by the user, possibly kept on a separate device, downloaded or based on user input with enough entropy (such as, password, security questions, hardware device).
Similar to existing 2FA systems, a user needs to prove ownership of at least 2 out of 3 (2/3) shares, in order to retrieve their private key. This initial setup provides several benefits.
## The user experience in mobile platforms
The user experience on mobile platforms differs significantly from the web platforms. This is because the user has to be redirected to a browser where they can sign in using their social accounts and then return to the app once they have been successfully authenticated. This user experience shifts the context between two applications, whereas, in the web platforms, the context remains within the browser only.
For the dapp share sign-in flow, we need to reconstruct the Shares `A` and `B`. `Share B` is managed by the sign-in service and is provided on successful authentication. Whereas in web platforms, `Share A` is stored in the browser context. We can still store it in the browser context for mobile devices, but this has a few risks like users deleting browser data by mistake. This is a bigger problem in mobile devices since the user doesn't realize that the browser is being used to sign in within the app and clearing the browser data can cause sign-in to fail. Hence, to tackle this issue, Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after the user signs in successfully.
## Dapp share in Android
Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after the user signs in successfully.
After a successful sign-in from a user, the user details are returned as a response to the application in mobile devices.
#### Sample response in Android
```json
{
"userInfo": {
"email": "w3a-heroes@web3auth.com",
"name": "Web3Auth Heroes",
"profileImage": "https://lh3.googleusercontent.com/a/Ajjjsdsmdjmnm...",
"authConnectionId": "torus",
"userId": "w3a-heroes@web3auth.com",
"authConnection": "google",
"groupedAuthConnectionId": "w3a-google-sapphire",
"dappShare": "", // 24 words of seed phrase will be sent only in case of custom auth connections
"idToken": "",
"oAuthIdToken": "", // will be sent only in case of custom auth connections
"oAuthAccessToken": "", // will be sent only in case of custom auth connections
"isMfaEnabled": false // Returns whether the user has enabled MFA or not
}
}
```
If you notice, the responses have a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dapp share is a supplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage.
Now, while signing in, the user can use their social accounts to obtain one share, and the application provides the dapp share, removing the need to store the share in the browser context and enabling user to sign in without repeating the full flow. This can be done by passing over the stored dapp share value in the `connectTo` method.
:::note
One major thing to note here is that the `dappShare` is only available for custom auth connections and not the standard Web3Auth auth connections. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dapp share, one has to use the custom authentication feature of Web3Auth. Also, the dapp share is only returned to users who have enabled 2FA to their account.
:::
```kotlin
web3Auth.connectTo(LoginParams(selectedLoginProvider, dappShare = "<24 words seed phrase>"))
```
## Example
```kotlin
class MainActivity : AppCompatActivity() {
private lateinit var web3Auth: Web3Auth
private fun signIn() {
val selectedLoginProvider = AuthConnection.GOOGLE
// Can be GOOGLE, FACEBOOK, TWITCH etc.
val loginCompletableFuture: CompletableFuture =
web3Auth.connectTo(LoginParams(selectedLoginProvider,
// focus-next-line
dappShare = "<24 words seed phrase>"))
loginCompletableFuture.whenComplete { loginResponse, error ->
if (error == null) {
// render logged in UI
} else {
// render error UI
}
}
}
override fun onCreate(savedInstanceState: Bundle?) {
// ...
// Setup UI and event handlers
val signInButton = findViewById