Permission Warnings

To use most chrome.* APIs and extension capabilities, your extension must declare its intent in the manifest, often in the "permissions" field. Some of these declarations result in a warning when a user installs your extension.

When you autoupdate your extension, the user might see another warning if the extension requests new permissions. These new permissions might be new APIs that your extension uses, or they might be new websites that your extension needs access to.

Examples of permission warnings

Here's a typical dialog that a user might see when installing an extension:

Permission warning: 'It can: Read and modify your data on api.flickr.com'

The warning about access to data on api.flickr.com is caused by the following lines in the extension's manifest:

"permissions": [
  "http://api.flickr.com/"
],

Note: You don't see permission warnings when you load an unpacked extension. You get permission warnings only when you install an extension from a .crx file.

If you add a permission to the extension when you autoupdate it, the user might see a new permission warning. For example, assume you add a new site and the "tabs" permission to the previous example:

"permissions": [
  "http://api.flickr.com/",
  "http://*.flickr.com/",
  "tabs"
],

When the extension autoupdates, the increased permissions cause the extension to be disabled until the user re-enables it. Here's the warning the user sees:

Warning text: 'The newest version of the extension Hello World requires more permissions, so it has been disabled. [Re-enable].'

Clicking the Re-enable button brings up the following warning:

Permission warning: 'It can: Read and modify your data on api.flickr.com; Access your browsing activity'

Warnings and their triggers

It can be surprising when adding a permission such as "tabs" results in the seemingly unrelated warning that the extension can access your browsing activity. The reason for the warning is that although the chrome.tabs API might be used only to open new tabs, it can also be used to see the URL that's associated with every newly opened tab (using their tabs.Tab objects).

The following table lists the warning messages that users can see, along with the manifest entries that trigger them.

Warning message Manifest entry that caused it Notes
Read and modify all your data on your computer and the websites you visit "plugins" The "plugins" permission is required by NPAPI plugins.
Read and modify your bookmarks "bookmarks" permission The "bookmarks" permission is required by the chrome.bookmarks module.
Read and modify your browsing history Any of the following:
  • "history" permission
  • "topSites" permission

The "history" permission is required by chrome.history.

The "topSites" permission is required by chrome.topSites.

Access your browsing activity Any of the following:
  • "tabs" permission
  • "webNavigation" permission

The "tabs" permission is required by the chrome.tabs and chrome.windows modules.

The "webNavigation" permission is required by the chrome.webNavigation module.

Manipulate settings that specify whether websites can use features such as cookies, JavaScript, plugins, geolocation, microphone, camera etc. "contentSettings" permission

The "contentSettings" permission is required by chrome.contentSettings.

Read and modify all your data on all websites you visit Any of the following:
  • "debugger" permission
  • "pageCapture" permission
  • "proxy" permission
  • A match pattern in the "permissions" field that matches all hosts
  • A "content_scripts" field with a "matches" entry that matches all hosts
  • "devtools_page"

The "debugger" permission is required by the debugger module.

The "proxy" permission is required by the chrome.proxy module.

Any of the following URLs match all hosts:

  • http://*/*
  • https://*/*
  • *://*/*
  • <all_urls>
Note that you may be able to avoid declaring all host permissions using the activeTab permission.
Read and modify your data on {list of websites} A match pattern in the "permissions" field that specifies one or more hosts, but not all hosts

Up to 3 sites are listed by name. Subdomains aren't treated specially. For example, a.com and b.a.com are listed as different sites.

On autoupdate, the user sees a permission warning if the extension adds or changes sites. For example, going from a.com,b.com to a.com,b.com,c.com triggers a warning. Going from b.a.com to a.com, or vice versa, also triggers a warning.

Manage your apps, extensions, and themes "management" permission The "management" permission is required by the chrome.management module.
Discover devices on your local network "mdns" permission The "mdns" permission is required by the chrome.mdns module.
Detect your physical location "geolocation" permission Allows the extension to use the proposed HTML5 geolocation API without prompting the user for permission.
Access data you copy and paste "clipboardRead" permission Allows the extension to use the following editing commands with document.execCommand():
  • "copy"
  • "cut"
Add printing destinations and access any jobs you submit to them "printerProvider" permission The "printerProvider" permission is required by the chrome.printerProvider module.
Manipulate privacy-related settings "privacy" permission The "privacy" permission is required by the chrome.privacy module.
Access the list of your signed-in devices "signedInDevices" permission The "signedInDevices" permission is required by the chrome.signedInDevices module.
Access all text spoken using synthesized speech "ttsEngine" permission The "ttsEngine" permission is required by the chrome.ttsEngine module.

Permissions that don't cause warnings

The following permissions don't result in a warning:

  • "activeTab"
  • "browsingData"
  • "chrome://favicon/"
  • "clipboardWrite"
  • "contextMenus"
  • "cookies"
  • "experimental"
  • "idle"
  • "notifications"
  • "storage"
  • "unlimitedStorage"
  • "webRequest"
  • "webRequestBlocking"

Testing permission warnings

If you'd like to see exactly which warnings your users will get, package your extension into a .crx file, and install it.

To see the warnings users will get when your extension is autoupdated, you can go to a little more trouble and set up an autoupdate server. To do this, first create an update manifest and point to it from your extension, using the "update_url" key (see Autoupdating). Next, package the extension into a new .crx file, and install the app from this .crx file. Now, change the extension's manifest to contain the new permissions, and repackage the extension. Finally, update the extension (and all other extensions that have outstanding updates) by clicking the chrome://extensions page's Update extensions now button.

API

You can get a list of permission warnings for any manifest with management.getPermissionWarningsByManifest.