Cordova - Whitelist

Cordova - Whitelist (Network Request and Navigation Control)

The cordova-plugin-whitelist provides a mechanism to control which network requests (images, XHRs, etc.) your application is allowed to make and which URLs can be opened by the application or external apps. When you create a new Cordova project, this plugin is typically installed by default. Its configuration is primarily managed through the config.xml file and Content Security Policy (CSP) meta tags in your index.html.

Security is paramount. Whitelisting helps prevent your application from accessing malicious sites or leaking data to unintended destinations.

Navigation Whitelist (<allow-navigation>)

The <allow-navigation> tag in config.xml controls which URLs the WebView itself can navigate to. If a URL is not matched by any <allow-navigation> tag, the navigation attempt will be blocked. By default, navigation to file:// URLs (your local app files) is allowed.

Example: Allowing navigation to https://example.com and its subdomains:

<!-- In config.xml -->
<allow-navigation href="https://example.com/*" />
<allow-navigation href="https://*.anotherexample.net/*" />

The asterisk * acts as a wildcard. https://example.com/* allows navigation to any page on example.com using HTTPS. To allow all subdomains, you can use *://*.example.com/* (though specifying the protocol like https* is generally safer than *).

Intent Whitelist (<allow-intent>)

The <allow-intent> tag in config.xml controls which URLs the application is allowed to ask the operating system to open. For example, opening a tel: link in the dialer app or an http: link in the system browser. Cordova’s default config.xml usually includes intents for common schemes like http, https, tel, sms, mailto, and geo.

Example: Allowing opening HTTP and HTTPS links in the system browser:

<!-- In config.xml -->
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />

Network Request Whitelist (<access origin>)

The <access> tag (from the core Cordova, often used in conjunction with the whitelist plugin for older Android versions, but CSP is the primary mechanism for modern Android and iOS) controls which network requests (e.g., XHRs, images) your app’s WebView can make. A common default is <access origin="*" />, which allows requests to any domain. For enhanced security, you should restrict this to only the domains your app needs to communicate with.

Example: Allowing network requests only to https://api.myapp.com:

<!-- In config.xml -->
<access origin="https://api.myapp.com" />
<!-- To allow subdomains: -->
<!-- <access origin="https://*.myapp.com" /> -->

Note: For newer Cordova versions (especially on Android using cordova-android@7+), CSP is the primary mechanism for controlling network requests from within the WebView. <access origin> might still influence plugin behavior or older platforms.

Content Security Policy (CSP)

Content Security Policy (CSP) is a crucial security layer that helps detect and mitigate certain types of attacks, such as Cross-Site Scripting (XSS) and data injection. It’s defined using a <meta> tag in your index.html file.

A modern default CSP for a Cordova app might look like this:

<!-- In index.html -->
<head>
    <meta http-equiv="Content-Security-Policy"
          content="default-src 'self' data: cdvfile: file: gap: https://ssl.gstatic.com;
                   style-src 'self' 'unsafe-inline';
                   script-src 'self' 'unsafe-eval';
                   media-src *;
                   img-src 'self' data: cdvfile: file: content:;">
    <!-- Adjust 'unsafe-inline' and 'unsafe-eval' as much as possible for better security -->
</head>

Explanation of common directives:

Example: A more restrictive CSP allowing resources only from self and a specific API domain:

<!-- In index.html -->
<head>
    <meta http-equiv="Content-Security-Policy"
          content="default-src 'self' https://api.example.com;
                   connect-src 'self' https://api.example.com wss://socket.example.com;
                   style-src 'self' 'unsafe-inline';
                   script-src 'self';
                   img-src 'self' data:;">
</head>

It’s a best practice to make your CSP as restrictive as possible. Start with a strict policy and gradually open up permissions as needed. For beginners, the default CSP provided by Cordova is a good starting point. As you become more familiar, you can tighten it based on your app’s specific requirements.

For further details, refer to the official cordova-plugin-whitelist documentation and MDN Web Docs for Content Security Policy.