Requesting the right permissions

Introduction

To help make users aware of the potential impact of installing an extension, Firefox will display a message showing what permissions an extension is requesting when it's installed. The prompt looks something like this:

Also, if an extension update requires additional permissions the user is prompted to approve the permissions before the updated version is installed:

If the user chooses not to approve the permissions and cancels the update, the previous version remains installed and available for use.

These messages have the potential to discourage some users from installing your extension, as the messages might suggest it's doing something “scary”. We provide users with an explanation of these permissions messages and guidance on how to judge if they're appropriate. However, there are several things you can do to reduce the likelihood of users abandoning the install of your extension because of these messages, these include:

• Make sure you aren't requesting unnecessary permissions.
• Request permissions at runtime, which enables you to ask for the permissions in context and offer a fall back if the user doesn't grant them.
• Describe why your extension is requesting its permissions in its AMO description.

Tip: Permission warnings aren't issued when you load an unpacked extension. For information on how to see the standard runtime permission flow, see Test permission requests.

Advised permissions

Not all permissions result in advice being given to the user. The permissions that trigger the display of a message and the messages they trigger are:

The following permissions don't get alerted to users:

• API permissions:
  • alarms
  • contextMenus
  • contextualIdentities
  • cookies
  • identity
  • idle
  • menus
  • storage
  • theme
  • webRequest
  • webRequestBlocking
• Other permissions:
  • unlimitedStorage
  • activeTab

Avoid unnecessary permissions

This section looks at situations where you might be asking for more permissions than your extension needs and what you should do about them.

Ask for only the permissions your extension uses

This may seem obvious, but if you create an extension by using an earlier example as a template or you remove a feature during development or testing, you may be asking for permissions your extension doesn't need. Addressing this is a case of doing a manual check of your code against the permissions (permissions and optional_permissions) that you're requesting in the extension's manifest.json.

Use "activeTab" rather than "tabs" and host permissions

Take an extension you're developing to help-color blind users. At the user's request you're going to look for and update CSS in a web page to replace colors the user may have difficulty distinguishing with safe colors. You obviously need to access and update CSS on every page your user visits. You could do this by requesting the "tabs" permission and host permission for "<all_urls>".

"permissions": [
  "<all_urls>",
  "tabs"
]

Requesting these permissions results in the user getting this advice:

The alternative is to request "activeTab". This permission provides your extension with the same capabilities but only for the active tab and only when run from the extension's UI (that is from a toolbar button, navigation bar button, context menu, or shortcut key).

Importantly, "activeTab" doesn't result in the display of a permissions message when installing the extension.

Avoid host permission "<all_urls>" if you can

As noted in the previous example, requesting host permission "<all_urls>" results in the permissions request message Access your data for all websites. If your extension is designed to work with one or a small number of websites or domains, narrow the request. On installation users will get details for the first four websites or domains you request access to.

If you request access to more than four websites or domains, the message will list the first three and indicate the number of other requests.

Avoid the "unlimitedStorage" permission

Only ask for "unlimitedStorage" permission if you expect your extension's local data storage to exceed 5MB if it's not going to exceed that amount, don't ask for it.

Note: Firefox doesn't currently restrict local storage size, although it does ask users to approve this permission request if you make it. Firefox may add a restriction in the future. If that happens, the limit is unlikely to be less than Chrome's current 5 MB restriction.

Request permissions at runtime

Users may not understand the context of permissions requested during installation. The alternative approach is to request permissions as they are needed, using the Permissions API, and thereby provide the user with context.

A typical scenario for using this approach is the "geoLocation" permission. Say you've written a note-taking extension that includes the ability to add a minimap of the note takers location. Requesting location access during installation might leave the user unclear why the extension needs to access location, so they might not install it. However, if permission to use location is requested when the user first tries the feature to add a minimap, they'll get a clearer understanding of why the permission is needed and be more likely to grant it. And should they choose not to grant the permission, the extension can offer a graceful fall-back—in this example, not adding the minimap—but the important outcome of this approach is that the user has installed and used your extension.

Making a runtime permission request is straightforward. Include any permissions you want to request under the manifest.json optional_permissions key. Then pass the permissions you want granted to permissions.request, which prompts the user to grant the permissions. true is returned if the user grants the request, false if they don't.

You can't request all the permissions available to "permissions" using optional permissions. You can't request the following API permissions:

• alarms
• background
• contentSettings
• contextualIdentities
• debugger
• downloads
• downloads.open
• find
• identity
• menus
• pageCapture
• privacy
• storage
• theme

There are a couple of things to note:

• You can only request permissions inside the handler for a user action, such as from a toolbar button (browser action), shortcut menu item, or similar.
• If you request several permissions at once they are either all granted or all declined, the user cannot choose to grant some and not others.

For more information about optional permissions, see optional_permissions and the permissions example.

Add information about permissions to your extensions AMO page

Permissions messages are most likely to prevent a user from installing your extension because they don't understand why permissions are being requested. While the user can get general advice on the impact of a permission, it may not be sufficient for them to understand why a permission is being requested in your extension.

To address this issue, provide information in your extension's AMO description that explains what permissions your extension is requesting and why.

A good example of this approach is Gesturefy, which offers users this advice: