> For the complete documentation index, see [llms.txt](/llms.txt). # 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 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. From v10, the Android SDK uses the **Auth Connection** terminology. Older SDK versions and documentation refer to an auth connection as a **Verifier**, an auth connection ID as a **Verifier ID**, and a grouped auth connection as an **Aggregate Verifier**. The `authConnectionConfig` parameter is a list of `AuthConnectionConfig` instances, each defining a specific authentication connection. After creating the auth connection from the [Embedded Wallets dashboard](https://developer.metamask.io), you can use the following parameters in the `AuthConnectionConfig`. **Table** | 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 ID of the grouped auth connection that this auth connection belongs to. Use it to combine multiple auth connections so users get the same wallet address regardless of the sign-in method. 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. | | `jwtParameters?` | Extra sign-in options for this auth connection, such as the Auth0 `domain`. It accepts `ExtraLoginOptions` as a value. | **Interface** ```kotlin data class AuthConnectionConfig( var authConnectionId: String, var authConnection: AuthConnection, var name: String? = null, var description: String? = null, var clientId: String, var groupedAuthConnectionId: String? = null, var logoHover: String? = null, var logoLight: String? = null, var logoDark: String? = null, var mainOption: Boolean? = false, var showOnModal: Boolean? = true, var showOnDesktop: Boolean? = true, var showOnMobile: Boolean? = true, val jwtParameters: ExtraLoginOptions? = null, ) 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 **Google** ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", 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 )) ), this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams(AuthConnection.GOOGLE) ) ``` **Facebook** ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", 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 ) ) ), this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams(AuthConnection.FACEBOOK) ) ``` **Auth0** ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", 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 )) ), this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, authConnectionId = "auth-connection-id", extraLoginOptions = ExtraLoginOptions( domain = "https://username.us.auth0.com" // Domain of your Auth0 app ) ) ) ``` **JWT** ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", authConnectionConfig = listOf( AuthConnectionConfig( authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard authConnection = AuthConnection.CUSTOM, clientId = "YOUR_WEB3AUTH_CLIENT_ID" ) ) ), this ) // SFA sign-in makes blocking network calls; call connectTo from a background thread val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, authConnectionId = "auth-connection-id", idToken = "YOUR_JWT_ID_TOKEN" ) ) ``` ## Configure extra sign-in options In addition to `authConnectionConfig`, 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 **Table** | 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. | | `login_hint?` | Hint for the sign-in flow, such as the user's email address. Usually set through `loginHint` in `LoginParams`, which overrides this 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 (`EmailFlowType.code` or `EmailFlowType.link`). Default is `EmailFlowType.code`. | | `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. | **Interface** ```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, var login_hint : String? = null, private var access_token : String? = null, private var flow_type : EmailFlowType = EmailFlowType.code, 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("link") link, @SerializedName("code") code, } ``` ### Single verifier Usage **Auth0** 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 import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", 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 )) ), this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, authConnectionId = "auth-connection-id", 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. ) ) ) ``` **Custom JWT** If you're using any other provider like Firebase, AWS identity services, or deploying your own custom JWT server, put the JWT into the `idToken` field of the `LoginParams` along with your `authConnectionId`. This uses SFA (Single Factor Auth) mode, which authenticates directly without a browser sign-in flow. SFA sign-in makes blocking network calls, so call `connectTo` from a background thread. See [SFA limitations](/embedded-wallets/sdk/android/#single-factor-auth-sfa-support). ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", authConnectionConfig = listOf(AuthConnectionConfig( authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard authConnection = AuthConnection.CUSTOM, clientId = "YOUR_WEB3AUTH_CLIENT_ID" )) ), this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, authConnectionId = "auth-connection-id", idToken = "Your JWT id token", ) ) ``` **Email Passwordless** 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 import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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, loginHint = "hello@web3auth.io", extraLoginOptions = ExtraLoginOptions( flow_type = EmailFlowType.code // Use code for OTP flow or link for magic link flow ) ) ) ``` **SMS Passwordless** 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 import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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.SMS_PASSWORDLESS, loginHint = "+91-9911223344" ) ) ``` ### 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. Set `authConnectionId` to the ID of each individual auth connection, and `groupedAuthConnectionId` to the ID of the grouped auth connection, both in `AuthConnectionConfig` and in `LoginParams`. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork 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", authConnectionConfig = listOf( AuthConnectionConfig( authConnectionId = "w3a-google", groupedAuthConnectionId = "aggregate-sapphire", authConnection = AuthConnection.GOOGLE, name = "Aggregate Login", clientId = getString(R.string.web3auth_google_client_id) ), AuthConnectionConfig( authConnectionId = "w3a-a0-email-passwordless", groupedAuthConnectionId = "aggregate-sapphire", authConnection = AuthConnection.CUSTOM, name = "Aggregate Login", clientId = getString(R.string.web3auth_auth0_client_id), jwtParameters = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", userIdField = "email", isUserIdCaseSensitive = false ) ) ) ), this ) // Google Login web3Auth.connectTo( LoginParams( AuthConnection.GOOGLE, authConnectionId = "w3a-google", groupedAuthConnectionId = "aggregate-sapphire" ) ) // Auth0 Login web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, authConnectionId = "w3a-a0-email-passwordless", groupedAuthConnectionId = "aggregate-sapphire", extraLoginOptions = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", userIdField = "email", isUserIdCaseSensitive = false ) ) ) ```