1---
  2title: Whitelist
  3description: Whitelist external content accessible by your app.
  4---
  5<!--
  6# license: Licensed to the Apache Software Foundation (ASF) under one
  7#         or more contributor license agreements.  See the NOTICE file
  8#         distributed with this work for additional information
  9#         regarding copyright ownership.  The ASF licenses this file
 10#         to you under the Apache License, Version 2.0 (the
 11#         "License"); you may not use this file except in compliance
 12#         with the License.  You may obtain a copy of the License at
 13#
 14#           http://www.apache.org/licenses/LICENSE-2.0
 15#
 16#         Unless required by applicable law or agreed to in writing,
 17#         software distributed under the License is distributed on an
 18#         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 19#         KIND, either express or implied.  See the License for the
 20#         specific language governing permissions and limitations
 21#         under the License.
 22-->
 23
 24# cordova-plugin-whitelist
 25
 26This plugin implements a whitelist policy for navigating the application webview on Cordova 4.0
 27
 28:warning: Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Whitelist%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
 29
 30## Installation
 31
 32You can install whitelist plugin with Cordova CLI, from npm:
 33
 34```
 35$ cordova plugin add cordova-plugin-whitelist
 36$ cordova prepare
 37```
 38
 39## Supported Cordova Platforms
 40
 41* Android 4.0.0 or above
 42
 43## Navigation Whitelist
 44Controls which URLs the WebView itself can be navigated to. Applies to
 45top-level navigations only.
 46
 47Quirks: on Android it also applies to iframes for non-http(s) schemes.
 48
 49By default, navigations only to `file://` URLs, are allowed. To allow others URLs, you must add `<allow-navigation>` tags to your `config.xml`:
 50
 51    <!-- Allow links to example.com -->
 52    <allow-navigation href="http://example.com/*" />
 53
 54    <!-- Wildcards are allowed for the protocol, as a prefix
 55         to the host, or as a suffix to the path -->
 56    <allow-navigation href="*://*.example.com/*" />
 57
 58    <!-- A wildcard can be used to whitelist the entire network,
 59         over HTTP and HTTPS.
 60         *NOT RECOMMENDED* -->
 61    <allow-navigation href="*" />
 62
 63    <!-- The above is equivalent to these three declarations -->
 64    <allow-navigation href="http://*/*" />
 65    <allow-navigation href="https://*/*" />
 66    <allow-navigation href="data:*" />
 67
 68## Intent Whitelist
 69Controls which URLs the app is allowed to ask the system to open.
 70By default, no external URLs are allowed.
 71
 72On Android, this equates to sending an intent of type BROWSEABLE.
 73
 74This whitelist does not apply to plugins, only hyperlinks and calls to `window.open()`.
 75
 76In `config.xml`, add `<allow-intent>` tags, like this:
 77
 78    <!-- Allow links to web pages to open in a browser -->
 79    <allow-intent href="http://*/*" />
 80    <allow-intent href="https://*/*" />
 81
 82    <!-- Allow links to example.com to open in a browser -->
 83    <allow-intent href="http://example.com/*" />
 84
 85    <!-- Wildcards are allowed for the protocol, as a prefix
 86         to the host, or as a suffix to the path -->
 87    <allow-intent href="*://*.example.com/*" />
 88
 89    <!-- Allow SMS links to open messaging app -->
 90    <allow-intent href="sms:*" />
 91
 92    <!-- Allow tel: links to open the dialer -->
 93    <allow-intent href="tel:*" />
 94
 95    <!-- Allow geo: links to open maps -->
 96    <allow-intent href="geo:*" />
 97
 98    <!-- Allow all unrecognized URLs to open installed apps
 99         *NOT RECOMMENDED* -->
100    <allow-intent href="*" />
101
102## Network Request Whitelist
103Controls which network requests (images, XHRs, etc) are allowed to be made (via cordova native hooks).
104
105Note: We suggest you use a Content Security Policy (see below), which is more secure.  This whitelist is mostly historical for webviews which do not support CSP.
106
107In `config.xml`, add `<access>` tags, like this:
108
109    <!-- Allow images, xhrs, etc. to google.com -->
110    <access origin="http://google.com" />
111    <access origin="https://google.com" />
112
113    <!-- Access to the subdomain maps.google.com -->
114    <access origin="http://maps.google.com" />
115
116    <!-- Access to all the subdomains on google.com -->
117    <access origin="http://*.google.com" />
118
119    <!-- Enable requests to content: URLs -->
120    <access origin="content:///*" />
121
122    <!-- Don't block any requests -->
123    <access origin="*" />
124
125Without any `<access>` tags, only requests to `file://` URLs are allowed. However, the default Cordova application includes `<access origin="*">` by default.
126
127
128Note: Whitelist cannot block network redirects from a whitelisted remote website (i.e. http or https) to a non-whitelisted website. Use CSP rules to mitigate redirects to non-whitelisted websites for webviews that support CSP.
129
130Quirk: Android also allows requests to https://ssl.gstatic.com/accessibility/javascript/android/ by default, since this is required for TalkBack to function properly.
131
132### Content Security Policy
133Controls which network requests (images, XHRs, etc) are allowed to be made (via webview directly).
134
135On Android and iOS, the network request whitelist (see above) is not able to filter all types of requests (e.g. `<video>` & WebSockets are not blocked). So, in addition to the whitelist, you should use a [Content Security Policy](http://content-security-policy.com/) `<meta>` tag on all of your pages.
136
137On Android, support for CSP within the system webview starts with KitKat (but is available on all versions using Crosswalk WebView).
138
139Here are some example CSP declarations for your `.html` pages:
140
141    <!-- Good default declaration:
142        * gap: is required only on iOS (when using UIWebView) and is needed for JS->native communication
143        * https://ssl.gstatic.com is required only on Android and is needed for TalkBack to function properly
144        * Disables use of eval() and inline scripts in order to mitigate risk of XSS vulnerabilities. To change this:
145            * Enable inline JS: add 'unsafe-inline' to default-src
146            * Enable eval(): add 'unsafe-eval' to default-src
147    -->
148    <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com; style-src 'self' 'unsafe-inline'; media-src *">
149
150    <!-- Allow everything but only from the same origin and foo.com -->
151    <meta http-equiv="Content-Security-Policy" content="default-src 'self' foo.com">
152
153    <!-- This policy allows everything (eg CSS, AJAX, object, frame, media, etc) except that 
154        * CSS only from the same origin and inline styles,
155        * scripts only from the same origin and inline styles, and eval()
156    -->
157    <meta http-equiv="Content-Security-Policy" content="default-src *; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'">
158
159    <!-- Allows XHRs only over HTTPS on the same domain. -->
160    <meta http-equiv="Content-Security-Policy" content="default-src 'self' https:">
161
162    <!-- Allow iframe to https://cordova.apache.org/ -->
163    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://cordova.apache.org">