This version of the documentation is outdated! Click here for the latest released version.

Whitelist Guide

Domain whitelisting is a security model that controls access to external domains over which your application has no control. Cordova provides a configurable security policy to define which external sites may be accessed. By default, new apps are configured to allow access to any site. Before moving your application to production, you should formulate a whitelist and allow access to specific network domains and subdomains.

For Android and iOS (as of their 4.0 releases), Cordova's security policy is extensible via a plugin interface. Your app should use the cordova-plugin-whitelist, as it provides better security and configurability than earlier versions of Cordova. While it is possible to implement your own whitelist plugin, it is not recommended unless your app has very specific security policy needs. See the cordova-plugin-whitelist for details on usage and configuration.

For other platforms, Cordova adheres to the W3C Widget Access specification, which relies on the <access> element within the app's config.xml file to enable network access to specific domains. For projects that rely on the CLI workflow described in The Command-Line Interface, this file is located in the project's top-level directory. Otherwise for platform-specific development paths, locations are listed in the sections below. (See the various Platform Guides for more information on each platform.)

The following examples demonstrate <access> whitelist syntax:

Access to google.com:

  <access origin="http://google.com" />

Access to the secure google.com (https://):

  <access origin="https://google.com" />

Access to the subdomain maps.google.com:

  <access origin="http://maps.google.com" />

Access to all the subdomains on google.com, for example mail.google.com and docs.google.com:
```
  <access origin="http://*.google.com" />
```
Access to all domains, for example, google.com and developer.mozilla.org:
```
  <access origin="*" />
```
This is the default value for newly created CLI projects.

Be aware that some websites may automatically redirect from their home page to a different url, such as using https protocol or to a country-specific domain. For example http://www.google.com will redirect to use SSL/TLS at https://www.google.com, and then may further redirect to a geography such as https://www.google.co.uk. Such scenarios may require modified or additional whitelist entries beyond your initial requirement. Please consider this as you are building your whitelist.

Note that the whitelist applies only to the main Cordova webview, and does not apply to an InAppBrowser webview or opening links in the system web browser.

Amazon Fire OS Whitelisting

Platform-specific whitelisting rules are found in res/xml/config.xml.

Android Whitelisting

As above, see cordova-plugin-whitelist for details. For cordova-android prior to 4.0.0, see older versions of this documentation.

iOS Whitelisting

As above, see cordova-plugin-whitelist for details. For cordova-ios prior to 4.0.0, see older versions of this documentation.

Application Transport Security (ATS) is new in iOS 9 (Xcode 7). This new feature acts as a whitelist for your app. The cli will automatically convert <access> and <allow-navigation> tags to the appropriate ATS directives.

The two tags mentioned above support these two new attributes below, which have their equivalents in ATS:

1. minimum-tls-version (String, defaults to 'TLSv1.2')
2. requires-forward-secrecy (Boolean, defaults to 'true')

See the ATS Technote for details.

BlackBerry 10 Whitelisting

The whitelisting rules are found in www/config.xml.

BlackBerry 10's use of wildcards differs from other platforms in two ways:

Any content accessed by XMLHttpRequest must be declared explicitly. Setting origin="*" does not work in this case. Alternatively, all web security may be disabled using the WebSecurity preference described in BlackBerry Configuration:
```
  <preference name="websecurity" value="disable" />
```
As an alternative to setting *.domain, set an additional subdomains attribute to true. It should be set to false by default. For example, the following allows access to google.com, maps.google.com, and docs.google.com:
```
  <access origin="http://google.com" subdomains="true" />
```
The following narrows access to google.com:
```
  <access origin="http://google.com" subdomains="false" />
```
Specify access to all domains, including the local file:// protocol:
```
  <access origin="*" subdomains="true" />
```

(For more information on support, see BlackBerry's documentation on the access element.)

Firefox OS

In Firefox OS there is no concept of whitelisting a specific domain. Instead there is a special permission called SystemXHR. There is a need to add this permission to config.xml:

<platform name="firefoxos">
	<permission name="systemXHR" privileged="true" description="load data from server" />
</platform>

The XMLHttpRequest object needs to be instantiated with two parameters mozAnon and mozSystem:

var request = new XMLHttpRequest({
	mozAnon: true,
	mozSystem: true});

This solution is transparent so there is no difference for other platforms.

Windows Phone Whitelisting

The whitelisting rules for Windows Phone 8 are found in the app's config.xml file.

Tizen Whitelisting

Whitelisting rules are found in the app's config.xml file. The platform relies on the same subdomains attribute as the BlackBerry platform. (For more information on support, see Tizen's documentation on the access element.)