Home
Docs
Blog
Articles
Home
Docs
Blog
Articles
Extensions
Welcome What's new in Chrome extensions Get help with Chrome extensions
Welcome Extensions 101 Development basics Run scripts on every page Inject scripts into the active tab Manage tabs Handle events with service workers
Welcome to Manifest V3 Extensions platform vision Overview of Manifest V3
What are themes? Frequently asked questions Extensions quality guidelines FAQ
Migrate to Manifest V3 Manifest V3 migration checklist Update the manifest Migrate to a service worker Update your code Replace blocking web request listeners Improve extension security Manifest V2 support timeline Known issues when migrating to Manifest V3
API reference Samples
Extension development overview Manifest file format Architecture overview Declare permissions About extension service workers Design the user interface Debugging extensions Samples
About extension service workers Extension service worker basics The extension service worker lifecycle Events in service workers
Message passing Content scripts Match patterns Using promises Cross-origin isolation
Cross-origin Network Requests Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools Fetching favicons OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API Native messaging Audio recording and screen capture
Protect user privacy Permission warning guidelines Stay secure Accessibility (a11y) Localization message formats Give users options
Extension hosting Alternative extension installation methods Installing extensions on Linux Tutorial: Google analytics
About Manifest V2 Getting started
What are extensions? What are themes? Frequently asked questions
Extension development overview Manifest file format Architecture overview Declare permissions Design the user interface Debugging extensions Samples
Message passing Content scripts Manage events with background scripts Match patterns Cross-origin isolation
Cross-origin XMLHttpRequest Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API
Protect user privacy Declare permissions and warn users Stay secure Accessibility (a11y) Localization message formats Give users options
Chrome Web Store Alternative extension distribution options Installing extensions on Linux Tutorial: Google analytics
Extensions
Welcome What's new in Chrome extensions Get help with Chrome extensions
Welcome Extensions 101 Development basics Run scripts on every page Inject scripts into the active tab Manage tabs Handle events with service workers
Welcome to Manifest V3 Extensions platform vision Overview of Manifest V3
What are themes? Frequently asked questions Extensions quality guidelines FAQ
Migrate to Manifest V3 Manifest V3 migration checklist Update the manifest Migrate to a service worker Update your code Replace blocking web request listeners Improve extension security Manifest V2 support timeline Known issues when migrating to Manifest V3
API reference Samples
Extension development overview Manifest file format Architecture overview Declare permissions About extension service workers Design the user interface Debugging extensions Samples
About extension service workers Extension service worker basics The extension service worker lifecycle Events in service workers
Message passing Content scripts Match patterns Using promises Cross-origin isolation
Cross-origin Network Requests Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools Fetching favicons OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API Native messaging Audio recording and screen capture
Protect user privacy Permission warning guidelines Stay secure Accessibility (a11y) Localization message formats Give users options
Extension hosting Alternative extension installation methods Installing extensions on Linux Tutorial: Google analytics
About Manifest V2 Getting started
What are extensions? What are themes? Frequently asked questions
Extension development overview Manifest file format Architecture overview Declare permissions Design the user interface Debugging extensions Samples
Message passing Content scripts Manage events with background scripts Match patterns Cross-origin isolation
Cross-origin XMLHttpRequest Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API
Protect user privacy Declare permissions and warn users Stay secure Accessibility (a11y) Localization message formats Give users options
Chrome Web Store Alternative extension distribution options Installing extensions on Linux Tutorial: Google analytics

Permission warning guidelines

Published on • Updated on

Overview

Chrome extensions enhance the user's browser experience. To do this extensions use Chrome APIs that require certain permissions. Some permissions are less intrusive and do not display a warning. Other permissions trigger a warning that users have to allow.

Example of permission warnings are displayed when the user adds a new extension
Permission warnings dialog displayed on installation.

When a new permission that triggers a warning is added, the extension will be disabled until the user accepts the new permission. See Updating permissions to learn how to test this behavior. 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>".

Best practices

Permission warnings describe the capabilities an API grants, but some warnings are harder to understand than others. Users are more likely to install extensions that follow these guidelines:

Request relevant permissions
Extensions are required to fulfill a single purpose and comply with the Use of permissions policy. Ensure you only request permissions that support the extension's main functionality.
Use optional permissions
Improve the onboarding experience by requesting permissions at runtime. This allows you to provide more context around a particular permission and lets users choose which features they want to enable. See Permissions API for implementation details.
Use the "activeTab" permission
This permission does not display a permission warning. It grants temporary host permission to the site the user is on. For more details, see Understanding the activeTab permission.

View warnings

To view an extension's permission warnings, you have the following options:

View using the Extension Update Testing Tool

Before you begin

  1. Install Node.js and NPM.
  2. Install Chromium.
  3. Clone the extension-update-testing-tool repository.
  4. Run npm install in the root of the repository.

Using the tool

  1. Run npm start.
  2. Open the local server at http://localhost:8080 in Chromium.
  3. Drag an unpacked extension (folder or .zip file) to the page.
  4. Follow the instructions under "Install manually" to download and install the extension.

Pack your extension manually

  1. Navigate to chrome://extensions

  2. Enable developer mode

  3. Click Pack Extension.

    Pack extension
    Developer mode enabled in the Extension management page

  4. Specify the path to the extension's folder in the extension root directory field. Ignore the Private key field for a first-time package.

  5. Click the Pack Extension button.

    Specify Extension Path then Click Pack Extension
    Specifying Extension Path

  6. Chrome will create two files, a .crx file and a .pem file. The .pem file contains the private key used to sign the extension. Make sure you remember which directory these files were saved.

    Packaged Extension Files
    Packaged Extension Files

  7. Keep the .pem file in a secret and secure place; it will be needed to update the extension.

  8. Install the .crx file by dropping it into the Extension's Management page.

    Drop File to Install
    Drop file to install

  9. After dropping the .crx file the browser will ask if the extension can be added and display warnings.

    Warning for New Tab Extension
    Warning for New Tab extension

Updating permissions

When an extension adds a new permission that triggers a warning it may temporarily disable it. The extension will be re-enabled only after the user agrees to accept the new permission.

To check if your extension will be disabled when adding a new permission, you have the following options:

Update using the Extension Update Testing Tool

These steps assume you followed the Using the Extension Update Testing Tool instructions to start the server.

Using the tool

  1. Add a new permission with warning.
  2. Increase the extension version number.
  3. Drag the unpacked extension (folder or .zip file) to the page.
  4. Go to chrome://extensions.
  5. Click on the Update button.

Update your extension manually

  1. Find the .crx file you just created in View Warnings.

  2. Rename it or delete it.

  3. Open your manifest.json and add any permission that triggers a warning.

  4. Go to chrome://extensions. Do not remove the previously installed package.

  5. Pack the extension again, but this time add the pem file in the second input.

    Pem file added when packing extension
    Packing extension dialog with pem file included.

  6. Drag the new packaged extension to the Extension Management page.

  7. You will see a dialog that prompts the user to accept the new permissions.

    Extension has been disabled
    Disabled extension warning
    Agree to permissions
    Requesting new permission dialog

Permissions warnings list

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.

PermissionDescriptionWarning
  • "http://*/*"
  • "https://*/*"
  • "*://*/*"
  • "<all_urls>"
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.
  • Access the page debugger backend
  • Read and change all your data on all websites
"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 on all signed-in devices
"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
"webAuthenticationProxy"Grants access to the chrome.webAuthenticationProxy API.Read and change all your data on all websites
"webNavigation"Grants access to the chrome.webNavigation API.Read your browsing history

Updated on • Improve article

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.