permissions

"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 パーミッションは:

• 拡張機能に storage.local API で制限する容量を超えられるようにする
• Firefox では「永続的な」IndexedDB データベースの作成を、データベース作成時にブラウザーからユーザーに許可を確認することなく、可能にする

例

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

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

  "permissions": ["tabs"]

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

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

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

ブラウザー実装状況

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.