Declare permissions and warn users
Published on • Updated on
An extension's ability to access websites and most Chrome APIs is determined by its declared permissions. Permissions should be restricted to only what is needed for its functionality. Limiting permissions establishes an extension's capabilities and reduces possible incursion to data if the extension is compromised by an attacker. Protect extensions and their users by implementing explicit, minimal and optional permissions.
Organize permissions
Permissions are known strings that refer to a Chrome API or match patterns that grant access to one or more hosts. They are listed in the manifest and specified as required permissions or optional permissions.
{
"name": "Permissions Extension",
...
"permissions": [
"activeTab",
"storage"
],
"optional_permissions": [
"topSites",
],
"host_permissions": [
"https://www.developer.chrome.com/*"
],
"optional_host_permissions": [
"http://*/*", "https://*/*"
],
...
"manifest_version": 3
}
Limit required permissions to only what is needed for the extension's core functionality. An extension should not request more permissions than it needs; do not future-proof by requesting permissions that may be needed in a future update.
Permissions needed for optional features should be registered as optional permissions. This allows users to decide how much access they are willing to provide an extension and which features are desired.
Identify required permissions
A simple extension may need to request multiple permissions, and many permissions display warnings on installation. Users are more likely to trust an extension with limited warnings or when permissions are explained to them.
![Extension permission warnings on installation](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/VVyazEJTquUP7aa6OZn0.png?auto=format)
Identify the core functionality of an extension and what permissions are required for it. Consider making features optional if they require permissions with warnings.
Trigger optional permissions with events
The optional permissions sample extension's core functionality is overriding the new tab page. One feature is displaying the user's goal of the day. This feature only requires the storage permission, which does not include a warning.
![Extension button that enables additional features](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/wtbjayBDYDyKZe2x580P.png?auto=format)
The extension has an additional feature; displaying the user's top sites. This feature requires the topSites permission, which has a warning.
![Extension warning for topSites API](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/5edHzqeUOJ8V6XHkjNBM.png?auto=format)
Developing features that rely on permissions with warnings as optional and introducing those features organically gives users a risk-free introduction to the extension. Additionally, this allows users to further customize their experience with an extension and creates an opportunity to explain warnings.
Substitute the activeTab permission
The "activeTab"
permission grants temporary access to the site the user is on and allows the extension to use host permissions on the current tab. It replaces "<all_urls>"
in many cases and displays no warning on installation.
For details, see Using the activeTab permission.
Allowing access
If an extension needs to access file://
URLs or operate in incognito mode, users will need to enable access for those features inside the extension's detail page at chrome://extensions.
![Allow file urls and incognito mode on the extension detial page](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/CXSHPxG4giUkzfGR67mY.png?auto=format)
An extension can detect if it is enabled in incognito mode by calling extension.isAllowedIncognitoAccess()
or able run on file://
URLs with extension.isAllowedFileSchemeAccess()
.
Understanding permissions
Permission warnings exist to describe the capabilities granted by an API to extension users, but some of these warnings may not be obvious at first. For instance, adding the "tabs"
permission results in a seemingly unrelated warning: the extension can Read your browsing activity. Although the Tabs API might be used to only open new tabs, it can also be used to see the URL that is associated with every newly opened tab by using their tabs.Tab objects.
When possible, implement optional permissions or a less powerful API to avoid alarming warnings.
Viewing warnings
No permission warnings will be displayed if an extension is loaded as an unpacked file. To view an extension's permission warnings, navigate to chrome://extensions
, ensure developer mode is enabled and click PACK EXTENSION.
![Developer Mode is Checked then Click Pack Extension](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/Jvm8mGpe3j0j0aydcRnR.png?auto=format)
Specify the path to the extension's folder in the Extension root directory field then click the Pack Extension button. Ignore the Private key field for a first-time package.
![Specify Extension Path then Click Pack Extension](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/vVw89rdJOdXFYxvgM9Sj.png?auto=format)
Chrome will create two files, a .crx
file and a .pem
file. The .pem
file contain the private key used to sign the extension.
![Packaged Extension Files](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/GLrVd51VTUF86K8gUxu8.png?auto=format)
Do not lose the private key! Keep the .pem
file in a secret and secure place; it will be needed to update the extension.
Install the .crx
file by dropping it into the Chrome Extension's Management page.
![Drop File to Install](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/KXm9vTnv5VRNZJ9e2AJt.png?auto=format)
After dropping the .crx
file the browser will ask if the extension can be added and display warnings.
![Warning for New Tab Extension](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/4vOB4X8ZNbdk321eAzKS.png?auto=format)
Permissions with warnings
Some permissions may not display warnings when paired with other permissions. For example, the "tabs"
warning will not show if the extension also requests "<all_urls>"
.
The permissions warning table is updated on a best-effort basis and may contain slight discrepancies with the current warnings. To verify the most recent warnings shown for extension permissions, follow the steps in Viewing Warnings.
Permission | Description | Warning |
---|---|---|
| Grants access to all hosts. Consider using the activeTab permission instead. | Read and change all your data on all websites |
"https://HostName.com/" | Grants access to "https://HostName.com/" . Consider using the activeTab permission instead. | Read and change your data on HostName.com |
"accessibilityFeatures.modify" | Allows the extension to modify individual accessibility feature states. See the chrome.accessibilityFeatures API for details. | Change your accessibility settings |
"accessibilityFeatures.read" | Allows the extension to read individual accessibility feature states. See the chrome.accessibilityFeatures API for details. | Read your accessibility settings |
"bookmarks" | Grants access to the chrome.bookmarks API. | Read and change your bookmarks |
"clipboardRead" | Required if the extension uses document.execCommand('paste') . | Read data you copy and paste |
"clipboardWrite" | Indicates the extension uses document.execCommand('copy') or document.execCommand('cut') . | Modify data you copy and paste |
"contentSettings" | Grants access to the chrome.contentSettings API. | Change your settings that control websites' access to features such as cookies, JavaScript, plugins, geolocation, microphone, camera etc. |
"debugger" | Grants access to the chrome.debugger API. |
|
"declarativeNetRequest" | Grants access to the chrome.declarativeNetRequest API. | Block content on any page |
"declarativeNetRequestFeedback" | Grants access to functions and events which return information on declarative rules matched. See the chrome.declarativeNetRequest API for details. | Read your browsing history |
"desktopCapture" | Grants access to the chrome.desktopCapture API. | Capture content of your screen |
"downloads" | Grants access to the chrome.downloads API. | Manage your downloads |
"favicon" | Grants access to the Favicon API. | Read the icons of the websites you visit |
"geolocation" | Allows the extension to use the HTML5 geolocation API without prompting the user for permission. | Detect your physical location |
"history" | Grants access to the chrome.history API. | Read and change your browsing history |
"identity.email" | Grants access to the email address through the chrome.identity API. | Know your email address |
"management" | Grants access to the chrome.management API. | Manage your apps, extensions, and themes |
"nativeMessaging" | Grants access to the native messaging API. | Communicate with cooperating native applications |
"notifications" | Grants access to the chrome.notifications API. | Display notifications |
"pageCapture" | Grants access to the chrome.pageCapture API. | Read and change all your data on all websites |
"privacy" | Grants access to the chrome.privacy API. | Change your privacy-related settings |
"proxy" | Grants access to the chrome.proxy API. | Read and change all your data on all websites |
"sessions" and "history" | Grants the extension access to the chrome.sessions API and chrome.history API. | Read and change your browsing history on all your signed-in devices |
"sessions" and "tabs" | Grants the extension access to the chrome.sessions API and privileged fields of the Tab objects. | Read your browsing history on all your signed-in devices |
"system.storage" | Grants access to the chrome.system.storage API. | Identify and eject storage devices |
"tabCapture" | Grants the extensions access to the chrome.tabCapture API. | Read and change all your data on all websites |
"tabGroups" | Grants access to the chrome.tabGroups API. | View and manage your tab groups |
"tabs" | Grants access to privileged fields of the Tab objects used by several APIs including chrome.tabs and chrome.windows. | Read your browsing history |
"topSites" | Grants access to the chrome.topSites API. | Read a list of your most frequently visited websites |
"ttsEngine" | Grants access to the chrome.ttsEngine API. | Read all text spoken using synthesized speech |
"webNavigation" | Grants access to the chrome.webNavigation API. | Read your browsing history |
Update permissions
When an extension is updated to include a new permission that triggers a warning it may temporarily disable it. The user will have to re-enable it after agreeing to any new warnings.
![Extension has been disabled](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/usZSh31pGiJxhhuKmM8B.png?auto=format)
![Agree to permissions](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/ZxRaaibQJSuZ6MZBvmmo.png?auto=format)
This can be avoided by making the new feature optional and adding new permission updates to optional_permissions
in the manifest.
Updated on • Improve article