For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

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

ParameterDescription
authConnectionIdThe name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts String as a value.
authConnectionType 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.
clientIdClient 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.

Usage​

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<Web3AuthResponse> = web3Auth.connectTo(
    LoginParams(AuthConnection.GOOGLE)
)

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​

ParameterDescription
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.

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.

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<Web3AuthResponse> = web3Auth.connectTo(
  LoginParams(
    AuthConnection.CUSTOM,
    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.
    )
  )
)

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.

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 = "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)
      )
    )
  ),
  this
)

// Google Login
web3Auth.connectTo(LoginParams(AuthConnection.GOOGLE))

// Auth0 Login
web3Auth.connectTo(LoginParams(
  AuthConnection.CUSTOM,
  extraLoginOptions = ExtraLoginOptions(
    domain = "https://web3auth.au.auth0.com",
    userIdField = "email",
    isUserIdCaseSensitive = false
  )
))
On this page