permissions

型 Array
必須項目か？ いいえ
例 
"permissions": [
  "*://developer.mozilla.org/*",
  "webRequest"
]

拡張機能が特別な権限を必要とする際には permission キーを使用します。このキーには文字列の配列を指定し、各文字列がパーミッションを要求します。

このキーを用いてパーミッションを要求した場合、ブラウザーはインストール時に「この拡張機能はこれだけの特権を要求しています」と通知し、これらの特権を許可しても大丈夫かとユーザーに確認します。ブラウザーはまた、インストール後にユーザーがアドオンの特権を調査することも許可します。

キーには以下の 3 種類があります。

  • host パーミッション
  • API パーミッション
  • activeTab パーミッション

host パーミッション

host パーミッションはマッチパターンとして指定します。それぞれのパターンによって、アドオンの要求する権限が有効となる URL の範囲を指定します。host パーミッションの例は "*://developer.mozilla.org/*" のようなものです。

この権限には以下が含まれます。

  • そのオリジンに対して、クロス-オリジン制約なしに XMLHttpRequest アクセス、 fetch アクセスができる権限（コンテンツスクリプトからのリクエストによるものも含みます）
  • そのオリジンによるページに（tabs.executeScript を用いて）スクリプトをプログラム的に挿入できる権限
  • webRequest API を用いて、そのホストからのイベントを受信できる権限
  • cookies API を用いて、そのホストの Cookie にアクセスできる権限（"cookies" API のパーミッションが指定されている場合）
  • ホスト名が完全修飾ドメインであり、ワイルドカードを含まない場合にトラッキング防止を回避。<all_urls> については除外。

Firefox では バージョン 56 以降で拡張機能は自動的に自身をオリジンとする host パーミッションを次の形式で取得します:

moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

ここで 60a20a9b-1ad4-af49-9b6c-c64c98c37920 は拡張機能の内部 ID です。拡張機能は extension.getURL() を呼び出すことでこの URL を取得できます:

browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/

API パーミッション

API パーミッションには、拡張機能から使用したい WebExtension API の名前をキーワードとして指定します。

現時点で使用できるキーワードは以下の通りです。

  • activeTab
  • alarms
  • background
  • bookmarks
  • browserSettings
  • browsingData
  • contentSettings
  • contextMenus
  • contextualIdentities
  • cookies
  • debugger
  • downloads
  • downloads.open
  • find
  • geolocation
  • history
  • identity
  • idle
  • management
  • menus
  • nativeMessaging
  • notifications
  • pageCapture
  • pkcs11
  • privacy
  • proxy
  • sessions
  • storage
  • tabs
  • theme
  • topSites
  • webNavigation
  • webRequest
  • webRequestBlocking

ほとんどの場合、パーミッションはその API へのアクセス権を付与するだけですが、以下のような例外があります。

  • tabs パーミッションを指定した場合、特別な tabs API のパーツ （Tab.url / Tab.title / Tab.faviconUrl）にアクセスすることが許可されます。 Firefox では、tabs.query() の queryInfo パラメーターに url を入れるのにも tabs が必要です。他の tabs API についてはパーミッションの要求なしで使用できます。
  • webRequestBlocking パーミッションを指定した場合、"blocking" 引数の使用が許可されます。これによってリクエストの変更やキャンセルが可能となります。
  • downloads.open パーミッションを指定した場合、downloads.open() API の利用が許可されます。

activeTab パーミッション

このパーミッションは "activeTab" と指定されます。拡張機能が activeTab パーミッションを持つなら、ユーザーが拡張機能と相互作用する時に、拡張機能はアクティブなタブ限定の特別な権限が許可されます。

"ユーザーの相互作用" とは次のようなものです:

  • ブラウザーアクションやページアクションをクリック
  • コンテキストメニュー項目を選択
  • 拡張機能によって定義されたキーボードショートカットをアクティベート

特別な権限とは:

  • chrome.tabs.executeScript と chrome.tabs.insertCSS を用いてタブに JavaScript や CSS をプログラム的に挿入できる能力
  • 現在のタブに、次の一部の tabs API の権限アクセス: Tab.url, Tab.title,  Tab.faviconUrl.

このパーミッションの意図は、拡張機能によくあるユースケースを、強力すぎるパーミッションを与えずに実行できるようにすることです。多くの拡張機能は「ユーザーが希望したら現在のページで何かをする」ことを希望しています。例えば、ユーザーがブラウザーアクションをクリックした時に現在のページでスクリプトを実行する拡張機能を考えます。activeTab パーミッションがない場合、拡張機能は <all_urls> の host パーミッションを要求する必要があります。しかし、これは拡張機能に必要以上の力を与えています: アクティブなタブで単にユーザーアクションに応答する代わりに、いかなるタブで、いかなるタイミングで、スクリプトを実行できます。

クリップボードのアクセス

拡張機能にクリップボードとやりとりできるようにする、2つの権限があります:

  • clipboardWrite: document.execCommand("copy") か document.execCommand("cut") を使ったクリップボードの書き込み
  • clipboardRead: document.execCommand("paste") を使ったクリップボードの読み込み

これについての詳細はクリップボードと相互作用するを見てください。

Unlimited storage

unlimitedStorage パーミッションは:

例

 "permissions": ["*://developer.mozilla.org/*"]

これは developer.mozilla.org ドメイン配下のページにアクセスする権限を要求しています。

  "permissions": ["tabs"]

tabs API を使用する権限を要求しています。

  "permissions": ["*://developer.mozilla.org/*", "tabs"]

上記の権限を両方ともに要求しています。

ブラウザー実装状況

BCD tables only load in the browser