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.

No changes to web3AuthOptions are required for custom authentication in v9. The loginConfig parameter from v8 has been removed.

Single connection​

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

The SDK handles the Firebase redirect natively. Obtain the Firebase idToken first (using the Firebase JS SDK), then pass it directly to connectTo:

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

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

  const login = async () => {
    const auth = getAuth()
    const result = await signInWithPopup(auth, new GoogleAuthProvider())
    const idToken = await result.user.getIdToken(true)

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

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

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. Replaces the v8 loginProvider field.
authConnectionId?NoDashboard Connection ID for the auth connection. Required when using AUTH_CONNECTION.CUSTOM or when you have multiple connections of the same type and need to target one specifically. Replaces the v8 loginConfig[key].verifier.
groupedAuthConnectionId?NoDashboard Grouped Connection ID when using grouped (aggregate) connections. Connections sharing the same groupedAuthConnectionId produce the same wallet address. Replaces the v8 loginConfig[key].verifierSubIdentifier.
idToken?NoA JWT issued by your authentication provider (Firebase, Auth0, Cognito, and so on). Pass this when using AUTH_CONNECTION.CUSTOM. The token is sent directly to the SDK instead of opening a browser redirect.
extraLoginOptions?NoAdditional OAuth hints passed to the authentication provider. Common fields: login_hint (email), domain (Auth0 domain), verifierIdField (JWT claim to use as the wallet identifier).
redirectUrl?NoOverride the global redirectUrl from web3AuthOptions for this login call only.
mfaLevel?NoOverride the global mfaLevel for this login call only.
curve?NoElliptic curve to use for key generation. Accepts SUPPORTED_KEY_CURVES.SECP256K1 (EVM) or SUPPORTED_KEY_CURVES.ED25519 (Solana). Defaults to the chain namespace.
sessionTime?NoOverride the global session duration (in seconds) for this login session only.
dappShare?NoCustom device share key for MFA-enabled wallets. Required when reconstructing a key with a custom share.
appState?NoArbitrary state string that is returned in the redirect callback. Useful for restoring application state after the OAuth redirect.

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