Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Permissions and Security

The Permissions Model - Ask for Less

Understand permissions, host_permissions, optional permissions and activeTab in Manifest V3, request access at runtime with chrome.permissions, and follow the least-privilege rule that store reviewers expect.

Permissions are the contract between your extension and the user. Every permission you request shows up in the install prompt and in the Chrome Web Store listing, and every extra permission makes users hesitate, slows review and widens the damage if your extension is ever compromised. The golden rule is least privilege: ask only for what a feature needs, and ask as late as possible.

Three kinds of access

Manifest V3 separates permissions into groups:

JSON
{
  "permissions": ["storage", "alarms", "contextMenus"],
  "host_permissions": ["https://api.example.com/*"],
  "optional_permissions": ["bookmarks"],
  "optional_host_permissions": ["https://*/*"]
}
  • permissions: access to Chrome APIs (storage, tabs, alarms, notifications, scripting, ...). Many are silent; some show a warning.
  • host_permissions: access to websites, written as match patterns. They allow fetch across origins without CORS, reading cookies for the site, and injecting scripts with chrome.scripting.
  • optional_permissions / optional_host_permissions: declared up front but only granted when your code asks and the user agrees.

Match patterns look like scheme://host/path. https://*.example.com/* is every https subdomain of example.com; <all_urls> is everything and triggers the strongest warning, so avoid it unless the extension truly works everywhere.

Permissions that warn the user

Some permissions produce an install-time warning such as "Read and change all your data on all websites". The scary ones include broad host_permissions, tabs (the sensitive tab fields), history, bookmarks, cookies with hosts, webRequest, downloads and management. Others, like storage, alarms and activeTab, show nothing.

Quiet permissions

storage Save settings
alarms Schedule work
activeTab Current tab on click
1 / 2

activeTab: the best trick in the book

"activeTab" gives temporary access to the tab the user is looking at, but only after they act: click your toolbar icon, press a keyboard shortcut or use a context-menu item. No install warning, no host list.

JSON
{
  "permissions": ["activeTab", "scripting"],
  "action": { "default_title": "Highlight this page" }
}
JavaScript
// service-worker.js (real extension code)
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ["highlight.js"]
  });
});

If your extension only needs to act on a page when the user asks, activeTab replaces a broad host permission entirely. See Content script injection for other ways to cut scope.

Requesting permissions at runtime

For features that are not essential, declare them as optional and request them from a user gesture (a click):

JavaScript
// options.js (real extension code)
document.getElementById("enable-bookmarks").addEventListener("click", async () => {
  const granted = await chrome.permissions.request({ permissions: ["bookmarks"] });
  if (granted) enableBookmarkSync();
  else showMessage("Bookmark sync stays off.");
});

The user sees a prompt. You can check, request and drop permissions:

JavaScript
await chrome.permissions.contains({ permissions: ["bookmarks"] });   // true or false
await chrome.permissions.request({ origins: ["https://example.com/*"] });
await chrome.permissions.remove({ permissions: ["bookmarks"] });
chrome.permissions.onRemoved.addListener(handleRevoked);              // user may revoke

Always code for the "no" answer, and for the user revoking later.

A permission gate stand-in

Real runtime requests must happen inside a user-gesture handler such as a click; calling them from a timer or on load fails.

Choosing narrow hosts

Compare these two manifests for an extension that adds a button to one site:

JSON
{ "host_permissions": ["<all_urls>"] }
JSON
{ "host_permissions": ["https://notes.example.com/*"] }

The second is a better install story and limits what a bug or a hijacked update could touch. The same applies to content script matches. Prefer exact origins and paths.

Reviewing your own manifest

A useful habit before every release: for each permission, write one sentence for the Web Store reviewer explaining which feature needs it. If you cannot, remove it. Unused permissions are a common reason for rejection (see Preparing for the Web Store).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the least-privilege approach for an extension that only acts when the user clicks its icon?

    activeTab grants temporary access to the current tab after a user gesture, with no install warning.
  2. 2. Where do match patterns such as https://api.example.com/* belong in Manifest V3?

    Website access goes in host_permissions (or optional_host_permissions); permissions is for Chrome APIs.
  3. 3. When can chrome.permissions.request be called successfully?

    Chrome requires a user gesture so users are not ambushed by prompts.
  4. 4. What should your code do when a request returns false?

    Treat denial as a normal outcome and degrade gracefully. Never nag.

Summary

  • Permissions for APIs, host_permissions for sites, and optional versions that you request later.
  • Prefer activeTab and narrow match patterns over <all_urls>.
  • Request optional permissions from a user gesture and handle denial and later revocation.
  • Justify every permission in one sentence, or drop it.

Next: Content Security Policy for Extensions