Skip to main content

Whitelisting your App Domain or Deep Links

Whitelisting URLs using the Developer Dashboard​

The Whitelist URL is the address you wish to authorize for your project. When implementing Web3Auth, it is important to whitelist the specific URLs from which you intend to make calls for user authentication. By doing so, you can ensure that these activities are conducted securely and efficiently. Remember to whitelist all relevant URLs to guarantee seamless integration with Web3Auth.

Type in the URL you wish to whitelist in the text box and click on the Add URL button. The URL will be added to the list of whitelisted URLs. You can add as many URLs as you want.

Dashboard Whitelist URL

Whitelisting for Mobile apps​

You can use the Developer Dashboard to whitelist URLs for mobile apps as well. For Android, you can whitelist the URL by adding the intent-filter making the links universal. For iOS, you can whitelist the URL by adding the Associated Domains in the Capabilities section of the project. For an extensive guide on deep linking and app linking for Android apps, please refer to the following blog.

Manual Whitelisting for Advanced Cases​

You can use the manual origin whitelisting method to whitelist URLs without using the Developer Dashboard. AuthAdapter accepts a parameter called originData inside the adapterSettings. originData is a key value pair where the key is the origin URL and the value is a signature. The signature is generated by whitelistUrl function from the @web3auth/auth package. The whitelistUrl function accepts the clientId, clientSecret and origin as parameters.

Note

Please perform this in a highly secure environment. The clientSecret should not be exposed to the public making this a risky process.

import { AuthAdapter } from "@web3auth/auth-adapter";
import { whitelistUrl } from "@web3auth/auth";
import { CommonPrivateKeyProvider } from "@web3auth/base-provider";

const clientId = "YOUR_CLIENT_ID"; // get from https://dashboard.web3auth.io
const clientSecret = "CORRESPONDING_CLIENT_SECRET"; // get from https://dashboard.web3auth.io
const origin = "https://example.com";

const privateKeyProvider = new CommonPrivateKeyProvider({ config: { chainConfig } });
const sig = await whitelistUrl(clientId, clientSecret, origin);

const authAdapter = new AuthAdapter({
  privateKeyProvider,
  adapterSettings: {
    originData: { [origin]: sig },
  },
});

How to secure deep linking via whitelisting strategies to avoid phishing attacks?​

Deep links are a type of link that can direct users deeper into a native mobile application. These are useful for connecting users to specific content within apps, but they don't have built-in mechanisms for verifying the authenticity of the destination app. This can potentially expose users to phishing attacks if they are directed to a malicious app instead.

On the other hand, Android's App Links and iOS's Universal Links (similar in purpose to App Links) are more secure versions of deep links. They include a verification process that Android and iOS use to confirm the link's destination. In the case of App Links, Android checks the app's digital asset links file hosted on the website's server, which contains information that links the website's URL to the app. This information must also be included in the app's manifest file. This process ensures that the app associated with the website is the legitimate destination, thereby mitigating the risk of phishing by not allowing malicious apps to intercept these links.

All OAuth applications work on whitelisting strategies. One may use App links or Universal links to secure the backlinking via whitelisting instead of deep links.

For more information, please refer to the following StackOverflow thread here.

Some security concerns should be addressed when it comes to deep linking:​

  • Deep links sometimes carry sensitive information, hence it's vital to avoid passing crucial information directly via the URLs.
  • Opaque tokens with limited validity should be utilized to minimize the risk of unauthorized access.
  • Secure channels, such as HTTPS should be used to transmit deep links to prevent eavesdropping.
tip

For detailed information on securing deep links, please refer to this blog.