Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

permissions

Type Array
Mandatory No
Example


"permissions": [
  "*://developer.mozilla.org/*",
  "webRequest"
]

Use the permissions key to request special powers for your extension. This key is an array of strings, and each string is a request for a permission.

If you request permissions using this key, then the browser may inform the user at install time that the extension is requesting certain privileges, and ask them to confirm that they are happy to grant these privileges. The browser may also allow the user to inspect an extension's privileges after installation.

The key can contain three kinds of permissions:

  • host permissions
  • API permissions
  • the activeTab permission

Host permissions

Host permissions are specified as match patterns, and each pattern identifies a group of URLs for which the extension is requesting extra privileges.

The extra privileges include:

  • XHR access to those origins
  • the ability to inject scripts programmatically (using tabs.executeScript) into pages served from those origins
  • the ability to receive events from the webRequest API for these hosts
  • the ability to access cookies for that host using the cookies API, as long as the "cookies" API permission is also included.

API permissions

API permissions are specified as keywords, and each keyword names a WebExtension API that the extension would like to use.

The following keywords are currently available:

  • alarms
  • bookmarks
  • contextMenus
  • cookies
  • downloads
  • downloads.open
  • history
  • idle
  • management
  • nativeMessaging
  • notifications
  • storage
  • tabs
  • webNavigation
  • webRequest
  • webRequestBlocking

In most cases the permission just grants access to the API, with the following exceptions:

  •  tabs gives you access to privileged parts of the tabs API: Tab.url, Tab.title, and Tab.faviconUrl. In Firefox, you also need tabs if you want to include url in the queryInfo parameter to  tabs.query(). The rest of the tabs API can be used without requesting any permission.
  • webRequestBlocking enables you to use the "blocking" argument, so you can modify and cancel requests.
  • downloads.open lets you use the downloads.open() API.

activeTab permission

This permission is specified as "activeTab". If an extension has the activeTab permission, then when the user interacts with the extension, the extension is granted extra privileges for the active tab only.

"User interaction" includes:

  • the user clicks the extension's browser action or page action
  • the user selects its context menu item
  • the user activates a keyboard shortcut defined by the extension (but this is currently broken in Firefox, see bug 1287159)

The extra privileges are:

  • the ability to inject JavaScript or CSS into the tab programmatically, using chrome.tabs.executeScript and chrome.tabs.insertCSS
  • access to the privileged parts of the tabs API for the current tab: Tab.url, Tab.title, and Tab.faviconUrl.

The intention of this permission is to enable extensions to fulfill a common use case, without having to give them very powerful permissions. Many extensions want to "do something to the current page when the user asks". For example, consider an extension that wants to run a script in the current page when the user clicks a browser action. If the  activeTab permission did not exist, the extension would need to ask for the host permission <all_urls>. But this gives the extension more power than it needs: it could now execute scripts in any tab, any time it likes, instead of just the active tab and just in response to a user action.

Clipboard access

There are two permissions which enable WebExtensions to interact with the clipboard:

  • clipboardWrite: write to the clipboard using document.execCommand("copy") or document.execCommand("cut")
  • clipboardRead: read from the clipboard using document.execCommand("paste")

See Interact with the clipboard for all the details on this.

Chrome incompatibilities

permissions

Firefox does not support the following permissions:

  • background
  • clipboardRead
  • clipboardWrite
  • geolocation
  • unlimitedStorage

Obviously, it doesn't support permissions for APIs that are themselves not supported.

Example

 "permissions": ["*://developer.mozilla.org/*"]

Request privileged access to pages under developer.mozilla.org.

  "permissions": ["tabs"]

Request access to the privileged pieces of the tabs API.

  "permissions": ["*://developer.mozilla.org/*", "tabs"]

Request both of the above permissions.

Document Tags and Contributors

 Contributors to this page: wbamberg, Makyen, evilpie, kmaglione
 Last updated by: wbamberg,