1. Introduction
2. Advised permissions
3. Avoid unnecessary permissions
4. Request permissions at runtime
5. Add information about permissions to your extensions AMO page

To inform users of the potential impact of installing an extension, Firefox displays a message showing whatpermissions 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 could discourage some users from installing your extension, as they might suggest it's doing something “scary”. We provide users with anexplanation of these permissions messages and guidance onhow to judge if they're appropriate. However, there are several things you can do to reduce the likelihood of users abandoning the installation 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 fallback if the user doesn't grant them.
• Describe why your extension is requesting its permissions in its AMO description.

Tip: Permission messages aren't issuedwhen you load an unpacked extension. For information on how to see the standard runtime permission flow, seeTest permission requests.

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

These permissions don't get alerted to users:

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

This may seem obvious, but if you create an extension using an earlier example as a template or remove a feature during development or testing, you may be asking for permissions your extension doesn't need. Addressing this involves manually checking your code against the permissions (permissions andoptional_permissions) that you're requesting in the extension'smanifest.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, your extension looks for and updates CSS on a web page to replace colors the user may have difficulty distinguishing with safe colors. Your extension must 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 display 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 few websites or domains, narrow the request. Then, when installing your extension, users see details for the first four websites or domains your extension requests access to.

If your extension requests access to more than four websites or domains, the message lists the first three and indicates 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.

Users may not understand the context of permissions requested during installation. To provide the user with context, request permissions when they are needed using thePermissions API.

Permissions that can be requested a runtime are known asoptional permissions. However, not all permissions can be requested at runtime. There are also a small number ofoptional-only permissions that can only be requested at runtime. An example of one such optional-only permission is theuserScript permission in Firefox.

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. Should they choose not to grant the permission, the extension can offer a graceful fallback—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 themanifest.jsonoptional_permissions key. Then, pass the permissions you want granted topermissions.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 these 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 need to request an optional-only permission, it must be the only permission you request in apermissions.request call.
• 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.

Users can also grant or revoke optional permissions anytime through an extension's option page. Your extension, therefore, needs to test to determine whether it has the necessary permissions or listen to thepermissions.onAdded andpermissions.onRemoved events.

For more information about optional permissions, seeoptional_permissions and thepermissions example.

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

Tags: add-ons beginner extensions how-to intermediate permissions 

Contributors: caitmuenster Zearin_Galaurum rebloor evilpie hellosct1 freaktechnik 

Last update: Zearin_Galaurum Mar 19, 2021