Ethereum Wallet

Descope allows you to create custom Social Login (OAuth) providers within the Authentication Methods page. This allows you to add any Social OAuth authentication within your application. This guide specifically covers the step by step configuration of a custom Ethereum Wallet OAuth provider.

Web3 Authentication

Web3 authentication represents a paradigm shift from traditional username and password-based authentication systems. Web3 authentication is a decentralized user authentication method that relies on blockchain technology and decentralized identity protocols. Unlike traditional web2 authentication methods that rely on centralized identity providers such as Google or Facebook, web3 authentication gives users more control over their data by allowing them to authenticate themselves using their own decentralized identities or digital wallets. This approach leverages blockchain-based technologies, such as smart contracts and decentralized applications (dApps), to provide a more secure and user-centric authentication process. Web3 authentication aims to enhance user privacy, reduce reliance on centralized identity providers, and increase the security of online interactions.

Web3 and Ethereum

In the context of Ethereum, web3 authentication involves the use of an Ethereum wallet as a means of identifying and authenticating a user. This approach leverages blockchain technology and public-key cryptography to create a more secure and user-friendly authentication process.

When a user wants to log in to a web3-enabled application, they can use their Ethereum wallet to sign a message or transaction, which is verified by the application's backend. This signed message proves that the user controls the private key associated with their Ethereum wallet and, therefore, confirms their identity. This process eliminates the need for users to remember passwords or rely on third-party services for authentication, giving them more control over their online identity. Moreover, because the user's private key never leaves their wallet, this authentication method is inherently more secure than traditional username and password-based systems.

Obtain Ethereum Client ID and Secret

Before creating the custom OAuth provider within the Descope console, you must obtain a Ethereum client ID and secret.

To obtain a client ID and secret, run the curl below. Note that if you have a customized domain, you will use your CNAME as configured within Project Settings. Example: auth.example.com would utilize the redirect URI of https://auth.example.com/v1/oauth/callback.

Terminal

curl -X POST https://oidc.login.xyz/register -d '{"redirect_uris":["https://api.descope.com/v1/oauth/callback"]}'

The response will look something like this which includes the client ID, secret, access token, and client URI.

{
  "client_id": "xxxxx",
  "client_secret": "xxxxx",
  "registration_access_token": "xxxxx",
  "registration_client_uri": "https://oidc.login.xyz/client/xxxxx",
  "redirect_uris": [
    "https://api.descope.com/v1/oauth/callback"
  ]
}

Creating Descope Custom Provider

Within the Customize Authentication Methods page, click the blue + Add custom provider in the top right corner. You can then give the provider the name of your choice, for this example, we will set the Provider Name to Ethereum. You can configure the logo which will be shown on the Social Auth button in your flow by selecting the edit button on the logo. You can also configure the Provider Description.

Configure Account Settings

Within the account settings section of your provider, you will configure the following items:

Client ID: This is the client ID from the response in the above curl.
Client Secret: This is the client secret from the response in the above curl.
Scopes: These are the configured scopes granted to Descope for the user within Ethereum. Scopes provides Ethereum users using third-party apps the confidence that only the information they choose to share will be shared. The minimum needed scopes for Descope to integrate with Ethereum are openid and profile.
Grant Type: Authorization Code grant type uses the default configured response method, while implicit is set to use the Form Post response method with "id_token" response type only.

Configure Connection Settings

Within the account settings section of your provider, you will configure the following items:

Authorization Endpoint: The endpoint to request authorization from the user. For Ethereum, this endpoint is https://oidc.login.xyz/authorize
Token Endpoint: The endpoint to exchange the authorization code for an access token. For Ethereum this endpoint is https://oidc.login.xyz/token
User Info Endpoint: The endpoint to get user details for attribute mapping. For Ethereum, this endpoint is https://oidc.login.xyz/userinfo

Note, these items can be found by running the below curl against the well known OpenID configuration URL.

Terminal

curl https://oidc.login.xyz/.well-known/openid-configuration

The response will look something like this which includes well known OpenID configuration items.

{
  "issuer": "https://oidc.login.xyz/",
  "authorization_endpoint": "https://oidc.login.xyz/authorize",
  "token_endpoint": "https://oidc.login.xyz/token",
  "userinfo_endpoint": "https://oidc.login.xyz/userinfo",
  "jwks_uri": "https://oidc.login.xyz/jwk",
  "registration_endpoint": "https://oidc.login.xyz/register",
  "scopes_supported": [
    "openid",
    "profile"
  ],
  "response_types_supported": [
    "code",
    "id_token",
    "token id_token"
  ],
  "subject_types_supported": [
    "pairwise"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "userinfo_signing_alg_values_supported": [
    "RS256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ],
  "claims_supported": [
    "sub",
    "aud",
    "exp",
    "iat",
    "iss",
    "preferred_username",
    "picture"
  ],
  "op_policy_uri": "https://oidc.login.xyz/legal/privacy-policy.pdf",
  "op_tos_uri": "https://oidc.login.xyz/legal/terms-of-use.pdf"
}

Once configured within the Descope console, your Connection Settings will look like the below.

Configure the Prompt

The prompt parameter significantly affect the user experience by specifying whether and how the user is prompted for authentication and consent. Tailoring the prompt behavior can lead to a smoother and more intuitive user experience. Also, in certain contexts, forcing a user to re-authenticate or re-consent can enhance security.

This configuration can be found under Prompt:

1. The 'login' prompt:

Usage: The prompt=login value forces the user to enter their credentials regardless of their current authentication state.
Use Case: This is particularly useful in scenarios where heightened security is required, such as sensitive transactions or changes in user settings.
Experience: It ensures that the user is indeed the one making the request, even if they are already logged in.

2. The 'consent' prompt

Usage: The prompt=consent value ensures that the user is explicitly asked to grant permissions, even if they have previously given consent.
Use Case: This is essential for applications that handle sensitive data or need explicit user permissions for certain actions.
Experience: It provides transparency and control to the user, ensuring they are aware of and agree to what permissions the application is requesting.

3. The 'select_account' prompt

Usage: Allows the user to select an account in multi-account scenarios.
Use Case: Useful in environments where users have multiple accounts (personal, work, etc.).
Experience: Enhances user convenience by enabling them to switch between different accounts seamlessly.

You can also change these prompts in the flow itself, rather than the custom provider configuration, if you want to use the same provider with different prompt values depending on your Flow configuration.

Configure User Attribute Mapping

Given the openid and profile scopes, the user can map the items in the above output from the well known OpenID configuration URL. The list is also added below.

{
    "claims_supported": [
        "sub",
        "aud",
        "exp",
        "iat",
        "iss",
        "preferred_username",
        "picture"
    ]
}

Given the available claims, you can map sub, preferred_username, and picture. See below for an example of the configured user attribute mapping.

Configure Advanced Settings

There are a few advanced options that can be configured within the custom provider in descope.

Optionally, you can choose to Manage tokens from provider if you want Descope to store the provider's access token in an encrypted state for later use.
Optionally, you can configure the Callback Domain which is only applicable if you have more than one CNAME associated with your application. If you have only one CNAME configured, it will default to your customized CNAME. Example: auth.example.com
Optionally, you can configure the Redirect URL which is the location to send the user upon successful OAuth authentication. If redirect URL is specified in the SDK/API call, it will override this value.
Optionally, you can choose Merge user accounts based on returned email address from provider, when selected, if an email is returned from this provider, it will automatically qualify as a login ID of the user; if the user already has an account with that email - the two accounts will be merged into one.

Check the configuration

Now that you have stepped through the above steps, your configuration should appear similar to the below.

Utilize within Descope Flow

We will now cover how to utilize the custom provider within a flow.

Within your Descope flow, update your login screen, adding the Ethereum button.

If your flow does not currently have the Sign Up or In / OAuth action, click on the blue + symbol in the top left, add a Sign Up or In / OAuth action.

Connect the Flow Actions

Now that you have configured the Sign Up or In action, connect the action to the Socials section of the login screen then to the next applicable step within your flow. Note that Ethereum does not store whether the email has been verified. It is suggested to check if the email is verified via a condition, then verify the email for the user.

Test your Flow

You can now test your flow within your application, the flow builder via clicking run, or within Descope Explorer. You may wish to have a Ethereum wallet plugin with your browser, for example MetaMask.

Utilize within Descope SDK

When utilizing your Ethereum custom provider within the Descope SDKs, you will pass the provider as Ethereum which is the name of the provider which you configured. Note that this is case sensitive to how you configured here.

Was this helpful?

On this page