To use most
extension APIs
and features, you must declare your extension's intent in the
manifest's
permissions fields. Extensions can request the following categories of permissions, specified using the respective manifest keys:
"permissions"
- Contains items from a list of
known strings
. Changes may trigger a
warning
.
"optional_permissions"
- Granted by the user at runtime, instead of at install time.
"content_scripts.matches"
- Contains one or more
match patterns
that allows content scripts to inject into one or more hosts. Changes may trigger a
warning
.
"host_permissions"
- Contains one or more
match patterns
that give access to one or more hosts. Changes may trigger a
warning
.
"optional_host_permissions"
- Granted by the user at runtime, instead of at install time.
Permissions help to limit damage if your extension is compromised by malware. Some permission warning are displayed to users for their consent before
installation or at runtime, as detailed in
Permission with warnings
.
Consider using
optional permissions
wherever the functionality of your extension
permits, to provide users with informed control over access to resources and data.
If an API requires a permission, its documentation explains how to declare it. For an
example, see
Storage API
.
Manifest
The following is an example of the permissions section of a
manifest
file:
manifest.json:
{
"name": "Permissions Extension",
...
"permissions": [
"activeTab",
"contextMenus",
"storage"
],
"optional_permissions": [
"topSites",
],
"host_permissions": [
"https://www.developer.chrome.com/*"
],
"optional_host_permissions":[
"https://*/*",
"http://*/*"
],
...
"manifest_version": 3
}
Host permissions
Host permissions allow extensions to interact with the URL's
matching patterns
. Some
Chrome APIs
require host permissions in addition to their own API permissions, which are documented on each reference page. Here are some examples:
Permissions with warnings
When an extension requests multiple permissions, and many of them display
warnings on installation, the user will see a list of warnings, like in the following example:
Users are more likely to trust an extension with limited warnings or when permissions are explained
to them. Consider implementing
optional permissions
or a less powerful API to avoid alarming
warnings. For best practices for warnings, see
Permission warnings guidelines
. Specific
warnings are listed with the permissions to which they apply in the
Permissions
reference list.
Adding or changing match patterns in the
"host_permissions"
and
"content_scripts.matches"
fields of the manifest filewill also trigger a
warning
. To learn more, see
Updating permissions
.
Allow access
If your extension needs to run on
file://
URLs or operate in incognito mode, users must give the extension access on its details page. You can find instructions for opening the details page under
Manage your extensions
.
Allow access to file URLs and incognito pages
- Right-click the extension icon in Chrome.
Choose
Manage Extension
.
Scroll down to enable access to file URLs or incognito mode.
To detect whether the user has allowed access, you can call
extension.isAllowedIncognitoAccess()
or
extension.isAllowedFileSchemeAccess()
.