How to Onboard Web3 users without a single line of blockchain code

Sep 22, 2022·Last updated on Sep 22, 2022

Share this article:

Unstoppable domains has partnered with Auth0 to bridge the gap to Web3, making it easier for developers to onboard blockchain users to their apps. The Login with Unstoppable Auth0 integration is the only Auth0 integration that supports cross chain login. While many agree Web3 is the future, there’s new development upskilling required to make it happen. We’ve heard from developers who want to add Web3 capabilities to their applications, but feel overwhelmed on how to:

  • Learn to work with various blockchains
  • Manage the code and user experience of wallet dialogs
  • Figure out how to represent a user as a wallet address
  • Communicate with users who want to maintain anonymity

This blog post will show how Login with Unstoppable removes barriers to Web3 when combined with our Auth0 social connection available today on the Auth0 Marketplace. Onboard blockchain users to your app, without writing any blockchain specific code.

Blockchain + OAuth2 + Auth0

The Unstoppable Domains social connection for Auth0 abstracts blockchain implementation details behind the OAuth2 standard. While many developers are new to blockchain, most will be familiar with OAuth2. This familiar approach enables your application to request OAuth2 scopes and receive claims to access Web3 user metadata, communication handles and blockchain specific details. Since the social connection is natively integrated into the Auth0 ecosystem, developers can tap into a rich client library to further simplify user management.

Live demo

Before jumping into the implementation details, it might be helpful to see the Unstoppable Domains social connection for Auth0 in action. We’ve provided a live sample application where you can test out the user experience when a user logs in using the social connection.

Source code to bootstrap your development

Auth0 provides a wealth of code samples to add user management capabilities to nearly all the popular frameworks. The live sample application above is based on Next.js, and we’ve provided the source code to show specifically how Web3 sign in can be added to your app with Unstoppable Domains.

Onboard Web3 users to your app

Ready to give it a try? This guide will take you step by step through the process to add cross-chain Web3 user management to your app.

Create an Unstoppable Domains client

Connecting your app to Auth0 requires the one-time creation of an Unstoppable Domains client ID. After following the instructions below to set up your app on the Unstoppable Domains client dashboard, you will have two pieces of information: client_id and client_secret. These values will be pasted directly into text fields in your new Auth0 social connection.

Demo video

Detailed instructions are provided below, but sometimes it helps to watch a video. https://www.loom.com/share/f1655c8e94cc464188472eea80d0f921

Step by Step Instructions

  1. Login to the Unstoppable Domains Client Dashboard
    undefinedundefinedundefined
  2. Create a new client ID
    undefinedundefinedundefined
  3. Add a redirect URI for your tenant
    undefinedundefined
  4. Click Advanced in the left navigation menu
    undefinedundefinedundefined
  5. Click Basic in the left navigation menu
  6. Click the Confirm Changes button at the top of the page
    undefinedundefinedundefined
  7. Add custom branding to your client (optional)
    undefinedundefined
  8. Click Confirm Changes save your configuration

Create an Auth0 account

Before using the Unstoppable Domains social connection for Auth0, you’ll need an Auth0 account. Auth0 provides a great guide to get started with your account. Once you’re finished, you can continue by adding the Unstoppable Domains social connection below.

Add a social connection

Now that you finished setting up your Unstoppable Domains client, you should have two key pieces of information: client_id and client_secret. These will be used in your Auth0 tenant in the following steps.

  1. Find the Unstoppable Domains social connection in the Auth0 Marketplace
  2. Select Add Integration 
  3. Read the necessary access requirements and click Continue.
  4. Configure the integration using the following fields:
    undefinedundefined
  5. Select the Permissions needed for your app
  6. Turn on or off syncing user profile attributes at each login
  7. Select Create
  8. Select the Applications tab and choose the apps that should use the Unstoppable Domains social connection

Add custom claims (optional)

Some of the Web3 claims offered by Unstoppable Domains are outside the standard OAuth2 specification. For example, the wallet_address claim may be useful to your app but is not included in the default profile. Adding a custom claim requires a few one-time steps in your Auth0 tenant. To learn more about the available scopes for Login with Unstoppable Domains, see our documentation.

 See the Auth0's example to add custom claims to a token for detailed information about the process. The process is summarized below, including some copy-and-paste code to create the custom claim in your Auth0 tenant.

Define an Auth0 login flow action

  1. In your Auth0 tenant click Actions in the navigation menu
  2. Click Flows menu item
  3. Click Login to define a new login flow
  4. Click the “+” icon to the right of Add Action 
    undefinedundefinedundefined
  5. Use the code editor to copy/paste the example code in the section below
    undefinedundefined
  6. Click Add to Flow in the deployment confirmation popup
  7. Drag and drop your new custom action into the login flow diagram

Code for custom claim

The code below can be pasted into the code editor in step 5 above, and is executed as part of every user login. It adds a wallet_address field to the data returned to your app. The same approach can be used to access any of the `app_metadata` or `user_metadata` stored in the Auth0 user object created after a successful login.

/
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
 const { strategy, name: connection } = event.connection;
 const { configuration, secrets } = event;
 
 if (strategy !== "oauth2" || connection !== "unstoppable-domains") {
   //This action only works for the unstoppable domains connection
   return;
 }
 
 const claim = "https://unstoppabledomains.com/wallet_address";
 const value = event.user.app_metadata.wallet_address;
 
 api.idToken.setCustomClaim(claim, value);
 api.accessToken.setCustomClaim(claim, value);
};

Example user object

Once your app is using the Unstoppable Domains social connection, Auth0 will be able to return user metadata to your app. As an example, consider the following user created by Auth0 using the Unstoppable Domains social connection.

 

{
   "app_metadata": {
       "wallet_address": "0xcAa2904218F62455EE24b5D56E43eAbE0a832672",
       "chain_id": 1
   },
   "created_at": "2022-08-25T20:33:06.469Z",
   "email": "mydomain.x@ud.me",
   "email_verified": true,
   "identities": [
       {
           "provider": "oauth2",
           "user_id": "unstoppable-domains|mydomain.x",
           "connection": "unstoppable-domains",
           "isSocial": true
       }
   ],
   "name": "John Doe",
   "nickname": "mydomain.x",
   "picture": "https://storage.googleapis.com/unstoppable-client-assets/images/user/5919054/3cd1b52b-686d-416d-9444-374581d38184.jpeg",
   "updated_at": "2022-09-13T12:55:30.500Z",
   "user_id": "oauth2|unstoppable-domains|mydomain.x",
   "user_metadata": {
       "social": {
           "twitter": "@handle"
       },
       "location": "Somewhere, World",
       "profileURL": "https://ud.me/mydomain.x"
   },
   "last_ip": "71.69.169.160",
   "last_login": "2022-09-13T12:55:30.500Z",
   "logins_count": 12,
   "blocked_for": [],
   "guardian_authenticators": []
}

Customize your app

Using Unstoppable Domains and Auth0, your app now has access to Web3 user metadata. The best part, you didn’t need to interact with the blockchain at all! From this point on, the sky is the limit now that you have permissioned access to the user’s Web3 identity, wallet address, communication details and more.

Troubleshooting

  1. Make sure the redirect_uri for the Unstoppable Domains client is in the correct format, as it must match exactly
    undefinedundefinedundefined
  2. The `email` and `wallet` scopes are required, but all the other scopes can be specified as optional
  3. Only configure your app to use the :optional or standard scope for each scope pair
    undefined

Each :optional flavor allows user to opt-out of the scope at the login prompt