Or how to avoid permissions discouraging users from installing your extensions.
With the introduction of Firefox Quantum (57) the handling of permissions when installing an extension changed. Previously, extensions were granted permissions silently. However, users are now informed of the permissions an extension is requesting when it's installed, with a message 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.
Displaying the permission messages improves the extension security model by making users aware of the potential impact of installing an extension. It also brings Firefox in line with other major browsers, where users have been informed about extensions' permission requests for some time.
Because Firefox users haven't seen permission requests during installation before, this change could discourage some of them 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. To view the permission warnings your extension will show to users, install your extension from its .xpi or .zip file. To install an unsigned .xpi or .zip file, you'll need to be running the Nightly or Developer Edition versions of Firefox with the
xpinstall.signatures.required preference set to
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:
Access your data for all websites
Access your data for sites in the [named] domain
Access your data in # other domains
Access your data for [named site]
Access your data on # other sites”
||Read and modify bookmarks|
||Read and modify browser settings|
||Clear recent browsing history, cookies, and related data|
||Download files and read and modify the browser’s download history|
||Open files downloaded to your computer|
||Read the text of all open tabs|
||Access your location|
||Access browsing history|
||Monitor extension usage and manage themes|
||Exchange messages with programs other than Firefox|
||Display notifications to you|
||Provide cryptographic authentication services|
||Read and modify privacy settings|
||Control browser proxy settings|
||Access recently closed tabs|
||Access browser tabs|
||Access browsing history|
||Access browser activity during navigation|
||Input data to the clipboard|
||Get data from the clipboard|
||Store unlimited amount of client-side data|
|The manifest key "devtools_page"||Extend developer tools to access your data in open tabs|
The permissions that display messages and the messages they display may be different in other browsers. For information about viewing the permission message in Chrome, see Viewing Warnings.
The following permissions don't get alerted to users:
- API permissions
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
"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).
"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:
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.
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 the following advice: