Sign in with Web3

Use your Web3 wallet to authenticate users with Supabase

Enable Sign In with Web3 to allow users to sign in to your application using only their Web3 wallet.

Supported Web3 wallets:

• All Solana wallets
• All Ethereum wallets

How does it work?#

Sign in with Web3 utilizes the EIP 4361 standard to authenticate wallet addresses off-chain. This standard is widely supported by the Ethereum and Solana ecosystems, making it the best choice for verifying wallet ownership.

Authentication works by asking the Web3 wallet application to sign a predefined message with the user's wallet. This message is parsed both by the Web3 wallet application and Supabase Auth to verify its validity and purpose, before creating a user account or session.

An example of such a message is:

1
2
3
4
5
6
7
8
9
10
11
12
example.com wants you to sign in with your Ethereum account:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2I accept the ExampleOrg Terms of Service: https://example.com/tosURI: https://example.com/loginVersion: 1Chain ID: 1Nonce: 32891756Issued At: 2021-09-30T16:25:24ZResources:- https://example.com/my-web2-claim.json

It defines the wallet address, timestamp, browser location where the sign-in occurred and includes a customizable statement (I accept...) which you can use to ask consent from the user.

Most Web3 wallets are able to recognize these messages and show a dedicated "Confirm Sign In" dialog validating and presenting the information in the message in a secure and responsible way to the user. Even if the wallet does not directly support these messages, it will use the message signature dialog instead.

Finally the Supabase Auth server validates both the message's contents and signature before issuing a valid User session to your application. Validation rules include:

• Message structure validation
• Cryptographic signature verification
• Timestamp validation, ensuring the signature was created within 10 minutes of the sign-in call
• URI and Domain validation, ensuring these match your server's defined Redirect URLs

The wallet address is used as the identity identifier, and in the identity data you can also find the statement and additional metadata.

Enable the Web3 provider#

In the dashboard navigate to your project's Authentication Providers section and enable the Web3 Wallet provider.

In the CLI add the following config to your supabase/config.toml file:

1
2
3
4
5
[auth.web3.solana]enabled = true[auth.web3.ethereum]enabled = true

Potential for abuse#

User accounts that sign in with their Web3 wallet will not have an email address or phone number associated with them. This can open your project to abuse as creating a Web3 wallet account is free and easy to automate and difficult to correlate with a real person's identity.

Control your project's exposure by configuring in the dashboard:

• Rate Limits for Web3
• Enable CAPTCHA protection

Or in the CLI:

1
2
3
4
5
6
7
8
[auth.rate_limit]# Number of Web3 logins that can be made in a 5 minute interval per IP address.web3 = 30[auth.captcha]enabled = trueprovider = "hcaptcha" # or other supported providerssecret = "0x0000000000000000000000000000000000000000"

Many wallet applications will warn the user if the message sent for signing is not coming from the page they are currently visiting. To further prevent your Supabase project from receiving signed messages destined for other applications, you must register your application's URL using the Redirect URL settings.

For example if the user is signing in to the page https://example.com/sign-in you should add the following configurations in the Redirect URL settings:

• https://example.com/sign-in/ (last slash is important)
• Alternatively set up a glob pattern such as https://example.com/**

Sign in with Ethereum#

Ethereum defines the window.ethereum global scope object that your app uses to interact with Ethereum Wallets. Additionally there is a wallet discovery mechanism (EIP-6963) that your app can use to discover all of the available wallets on the user's browser.

To sign in a user with their Ethereum wallet make sure that the user has installed a wallet application. There are two ways to do this:

1. Detect the window.ethereum global scope object and ensure it's defined. This only works if your user has only one wallet installed on their browser.
2. Use the wallet discovery mechanism (EIP-6963) to ask the user to choose a wallet before they continue to sign in. Read the MetaMask guide on the best way to support this.

1
2
3
4
const { data, error } = await supabase.auth.signInWithWeb3({  chain: 'ethereum',  statement: 'I accept the Terms of Service at https://example.com/tos',})

Sign in with Solana#

1
2
3
4
const { data, error } = await supabase.auth.signInWithWeb3({  chain: 'solana',  statement: 'I accept the Terms of Service at https://example.com/tos',})

Frequently asked questions#

How to associate an email address, phone number or social login to a user signing in with Web3?#

Web3 wallets don't expose any identifying information about the user other than their wallet address (public key). This is why accounts that were created using Sign in with Web3 don't have any email address or phone number associated.

To associate an email address, phone number or other social login with their account you can use the supabase.auth.updateUser() or supabase.auth.linkIdentity() APIs.