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 in React Native SDK

Custom authentication lets you integrate your own identity provider, Google with your own Client ID, Firebase, Auth0, AWS Cognito, or any custom JWT issuer, so that the resulting wallet is tied to your user identity rather than to Web3Auth's default verifiers.

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.

Prerequisites​

Create a Connection in the Authentication tab of your project on the Embedded Wallets dashboard. The dashboard will give you an Auth Connection ID which you pass to connectTo at sign-in time.

You don't need to change web3AuthOptions for custom authentication. Pass the connection ID to connectTo at sign-in time.

Single connection​

Use AUTH_CONNECTION.CUSTOM with authConnectionId to target a specific connection registered on the dashboard.

Sign the user in with Firebase first, for example with @react-native-firebase/auth, then pass the Firebase ID token to connectTo as idToken. The SDK doesn't open a browser for this flow.

import auth from '@react-native-firebase/auth'
import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'
import { Button } from 'react-native'

function FirebaseLoginButton() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const login = async () => {
    // Sign in with any Firebase method, then read the ID token
    const { user } = await auth().signInAnonymously()
    const idToken = await user.getIdToken(true)

    await connectTo({
      authConnection: AUTH_CONNECTION.CUSTOM,
      authConnectionId: 'w3a-firebase-demo', // Dashboard Connection ID
      idToken,
    })
  }

  return <Button title="Sign in with Firebase" disabled={loading} onPress={login} />
}

Bring your own JWT (idToken)​

When you pass idToken to connectTo, the SDK verifies the token with the Embedded Wallets network and derives the wallet directly, without an in-app browser. Keep the following in mind:

  • Set authConnection to AUTH_CONNECTION.CUSTOM and authConnectionId to the dashboard connection that verifies your JWT issuer.
  • In SDK v10.0.0, the SDK reads the user identifier from the token's user_id claim. Firebase ID tokens include user_id. Tokens from other issuers must include a user_id claim that matches the identifier field configured for the connection.
  • extraLoginOptions doesn't apply to this flow.
  • These sessions don't have an Embedded Wallets access token, so useWeb3Auth().isAuthorized is false and useAccessToken returns null.
  • If the user already enabled MFA for this connection, connectTo fails. Use the browser-based flow (without idToken) for users with MFA.

Grouped connections (aggregate verifiers)​

Grouped connections allow users to sign in through different providers and always receive the same wallet address, as long as the underlying email or user identifier matches. This is useful for "Sign in with Google" and "Sign in with email" mapping to the same wallet.

Configure a Grouped Connection on the dashboard, then pass the group ID as groupedAuthConnectionId alongside each individual connection's authConnectionId:

import { AUTH_CONNECTION, useWeb3AuthConnect } from '@web3auth/react-native-sdk'

function GroupedLoginView() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const loginWithGoogle = () =>
    connectTo({
      authConnection: AUTH_CONNECTION.GOOGLE,
      authConnectionId: 'w3a-google', // individual connection
      groupedAuthConnectionId: 'aggregate-sapphire', // grouped connection
    })

  const loginWithEmail = () =>
    connectTo({
      authConnection: AUTH_CONNECTION.CUSTOM,
      authConnectionId: 'w3a-a0-email-passwordless',
      groupedAuthConnectionId: 'aggregate-sapphire', // same group, same wallet
    })

  return (
    <View>
      <Button title="Sign in with Google" disabled={loading} onPress={loginWithGoogle} />
      <Button title="Sign in with Email" disabled={loading} onPress={loginWithEmail} />
    </View>
  )
}

Both buttons produce the same wallet address for users whose email matches across providers.

connectTo parameter reference​

ParameterRequiredDescription
authConnectionYesAuthentication method. Pass an AUTH_CONNECTION.* constant.
authConnectionId?NoConnection ID from the dashboard. Required for AUTH_CONNECTION.CUSTOM and for grouped connections. Also use it to target a specific connection when you have several of the same type.
groupedAuthConnectionId?NoGrouped connection ID from the dashboard. Connections in the same group produce the same wallet for the same user.
idToken?NoJWT from your own auth provider. When set, the SDK skips the in-app browser and derives the wallet from the token directly. Requires authConnectionId. See Custom authentication.
extraLoginOptions?NoExtra OAuth parameters for browser-based sign-in, for example login_hint (email or phone number for passwordless), domain (Auth0 domain), and verifierIdField (JWT claim used as the user ID).
mfaLevel?NoWhen to show the MFA setup screen: 'optional', 'mandatory', or 'none' (MFA_LEVELS.OPTIONAL, MFA_LEVELS.MANDATORY, MFA_LEVELS.NONE).
curve?NoKey curve: SUPPORTED_KEY_CURVES.SECP256K1 or SUPPORTED_KEY_CURVES.ED25519.
dappShare?NoDapp share for MFA-enabled custom connections. The SDK stores and reuses the dapp share automatically; see Dapp share.
appState?NoCustom state string returned in userInfo.appState after sign-in.
dappUrl?NoCustom redirect URL for the manage MFA flow.

extraLoginOptions field reference​

FieldTypeDescription
domain?stringYour identity provider domain (for example, https://example.auth0.com).
login_hint?stringPre-filled email address for email passwordless flows.
verifierIdField?stringThe JWT claim to use as the user identifier (typically sub or email). Must match the setting in the dashboard connection.
isVerifierIdCaseSensitive?booleanWhether the verifier ID field comparison is case-sensitive. Default is true.
client_id?stringClient ID of the OAuth application (if different from clientId in web3AuthOptions).
leeway?stringClock skew tolerance in seconds for JWT expiry checks. Maximum 120.
scope?stringSpace-separated list of OAuth scopes to request.
id_token_hint?stringA previously issued ID token to pass as a hint.
redirect_uri?stringOverride the redirect URI for the OAuth flow.
On this page