chrome/common/extensions/docs/templates/articles/permission_warnings.html

   1 <h1>Permission Warnings</h1>
   2
   3
   4 <!--
   5 NOTE: When this doc is updated, the online help should also be updated:
   6 https://support.google.com/chrome_webstore/answer/186213
   7
   8 We should periodically look at
   9 http://src.chromium.org/viewvc/chrome/trunk/src/chrome/app/generated_resources.grd?view=markup
  10 to make sure that we're covering all messages. Search for
  11 IDS_EXTENSION_PROMPT_WARNING
  12 (e.g. IDS_EXTENSION_PROMPT_WARNING_BROWSING_HISTORY).
  13 -->
  14
  15 <p>
  16 To use most chrome.* APIs and extension capabilities,
  17 your extension must declare its intent in the
  18 <a href="manifest">manifest</a>,
  19 often in the "permissions" field.
  20 Some of these declarations
  21 result in a warning when
  22 a user installs your extension.
  23 </p>
  24
  25 <p>
  26 When you autoupdate your extension,
  27 the user might see another warning
  28 if the extension requests new permissions.
  29 These new permissions might be new APIs that your extension uses,
  30 or they might be new websites
  31 that your extension needs access to.
  32 </p>
  33
  34
  35 <h2 id="examples"> Examples of permission warnings </h2>
  36
  37 <p>
  38 Here's a typical dialog
  39 that a user might see when installing an extension:
  40 </p>
  41
  42 <img src="{{static}}/images/perms-hw1.png"
  43   width="490" height="193"
  44   alt="Permission warning: 'It can: Read and modify your data on api.flickr.com'"
  45   />
  46
  47 <p>
  48 The warning about access to data on api.flickr.com
  49 is caused by the following lines
  50 in the extension's manifest:
  51 </p>
  52
  53 <pre data-filename="manifest.json">
  54 "permissions": [
  55   <b>"http://api.flickr.com/"</b>
  56 ],
  57 </pre>
  58
  59 <p class="note">
  60 <b>Note:</b>
  61 You don't see permission warnings when
  62 you load an unpacked extension.
  63 You get permission warnings only when you install an extension
  64 from a <code>.crx</code> file.
  65 </p>
  66
  67 <p>
  68 If you add a permission to the extension when you autoupdate it,
  69 the user might see a new permission warning.
  70 For example,
  71 assume you add a new site and the "tabs" permission
  72 to the previous example:
  73 </p>
  74
  75 <pre data-filename="manifest.json">
  76 "permissions": [
  77   "http://api.flickr.com/",
  78   <b>"http://*.flickr.com/",
  79   "tabs"</b>
  80 ],
  81 </pre>
  82
  83 <p>
  84 When the extension autoupdates,
  85 the increased permissions
  86 cause the extension to be disabled
  87 until the user re-enables it.
  88 Here's the warning the user sees:
  89 </p>
  90
  91 <img src="{{static}}/images/perms-hw2-disabled.png"
  92   width="332" height="208"
  93   alt="Warning text: 'The newest version of the extension Hello World requires more permissions, so it has been disabled. [Re-enable].'"
  94   />
  95
  96 <p>
  97 Clicking the Re-enable button
  98 brings up the following warning:
  99 </p>
 100
 101 <img src="{{static}}/images/perms-hw2.png"
 102   width="490" height="193"
 103   alt="Permission warning: 'It can: Read and modify your data on api.flickr.com; Access your browsing activity'"
 104   />
 105
 106
 107 <h2 id="warnings"> Warnings and their triggers </h2>
 108
 109 {{^is_apps}}
 110 <p>
 111 It can be surprising when adding a permission such as "tabs"
 112 results in the seemingly unrelated warning
 113 that the extension can access your browsing activity.
 114 The reason for the warning is that
 115 although the <code>chrome.tabs</code> API
 116 might be used only to open new tabs,
 117 it can also be used to see the URL that's associated
 118 with every newly opened tab
 119 (using their $(ref:tabs.Tab) objects).
 120 </p>
 121 {{/is_apps}}
 122
 123 <p>
 124 The following table lists the warning messages
 125 that users can see,
 126 along with the manifest entries
 127 that trigger them.
 128 </p>
 129
 130 <p>
 131 <table>
 132   <tr>
 133     <th> Warning message </th>
 134     <th> Manifest entry that caused it </th>
 135     <th> Notes </th>
 136   </tr>
 137 <tr>
 138   <td style="font-weight:bold">
 139     <!-- IDS_EXTENSION_PROMPT_WARNING_FULL_ACCESS -->
 140     Read and modify all your data on your computer and the websites you visit
 141   </td>
 142   <td>
 143     "plugins"
 144   </td>
 145   <td>
 146     The "plugins" permission is required by
 147     <a href="npapi">NPAPI plugins</a>.
 148   </td>
 149 </tr>
 150
 151 <tr>
 152   <td style="font-weight:bold">
 153     <!-- IDS_EXTENSION_PROMPT_WARNING_BOOKMARKS -->
 154     Read and modify your bookmarks
 155   </td>
 156   <td>
 157     "bookmarks" permission
 158   </td>
 159   <td>
 160     The "bookmarks" permission is required by the
 161     <a href="bookmarks"><code>chrome.bookmarks</code></a> module.
 162   </td>
 163 </tr>
 164
 165 <tr>
 166   <td style="font-weight:bold">
 167     <!-- IDS_EXTENSION_PROMPT_WARNING_BROWSING_HISTORY -->
 168     Read and modify your browsing history
 169   </td>
 170   <td>
 171     <!-- HasEffectiveBrowsingHistoryPermission -->
 172      Any of the following:
 173     <ul>
 174       <li> "history" permission </li>
 175       <li> "topSites" permission </li>
 176     </ul>
 177   </td>
 178   <td>
 179     <p>
 180       The "history" permission is required by
 181       <a href="history"><code>chrome.history</code></a>.
 182     </p>
 183     <p>
 184       The "topSites" permission is required by
 185       <a href="topSites"><code>chrome.topSites</code></a>.
 186     </p>
 187   </td>
 188 </tr>
 189
 190 <tr>
 191   <td style="font-weight:bold">
 192     <!-- IDS_EXTENSION_PROMPT_WARNING_TABS -->
 193     Access your browsing activity
 194   </td>
 195   <td>
 196     <!-- HasEffectiveBrowsingHistoryPermission -->
 197     Any of the following:
 198     <ul>
 199       <li> "tabs" permission </li>
 200       <li> "webNavigation" permission </li>
 201     </ul>
 202   </td>
 203   <td>
 204     <p>
 205       The "tabs" permission is required by the
 206       <a href="tabs"><code>chrome.tabs</code></a> and
 207       <a href="windows"><code>chrome.windows</code></a> modules.
 208     </p>
 209     <p>
 210       The "webNavigation" permission is required by the
 211       <a href="webNavigation"><code>chrome.webNavigation</code></a> module.
 212     </p>
 213   </td>
 214 </tr>
 215
 216 <tr>
 217   <td style="font-weight:bold">
 218     <!-- IDS_EXTENSION_PROMPT_WARNING_CONTENT_SETTINGS -->
 219     Manipulate settings that specify whether websites can use features such as cookies, JavaScript, plugins, geolocation, microphone, camera etc.
 220   </td>
 221   <td>
 222     <!-- HasEffectiveBrowsingHistoryPermission -->
 223      "contentSettings" permission
 224   </td>
 225   <td>
 226     <p>
 227       The "contentSettings" permission is required by
 228       <a href="contentSettings"><code>chrome.contentSettings</code></a>.
 229     </p>
 230   </td>
 231 </tr>
 232
 233 <tr>
 234   <td style="font-weight:bold">
 235     <!-- IDS_EXTENSION_PROMPT_WARNING_ALL_HOSTS -->
 236     Read and modify all your data on all websites you visit
 237   </td>
 238   <td>
 239     <!-- HasEffectiveAccessToAllHosts() -->
 240     Any of the following:
 241     <ul>
 242       <li> "debugger" permission </li>
 243       <li> "pageCapture" permission </li>
 244       <li> "proxy" permission </li>
 245       <li> A match pattern in the "permissions" field
 246         that matches all hosts </li>
 247       <li> A&nbsp;"content_scripts" field with a "matches" entry
 248         that matches all hosts </li>
 249       <li> "devtools_page" </li>
 250     </ul>
 251   </td>
 252   <td>
 253     <p>
 254       The "debugger" permission is required by the
 255       <a href="debugger">debugger</a> module.
 256     </p>
 257
 258     <p>
 259       The "proxy" permission is required by the
 260       <a href="proxy"><code>chrome.proxy</code></a> module.
 261     </p>
 262
 263     <p>
 264       Any of the following URLs match all hosts:
 265     </p>
 266     <ul>
 267       <li> <code>http://*/*</code> </li>
 268       <li> <code>https://*/*</code> </li>
 269       <li> <code>*://*/*</code> </li>
 270       <li> <code>&lt;all_urls&gt;</code> </li>
 271     </ul>
 272     <strong>Note that you may be able to avoid declaring all host permissions using the <code><a href="activeTab">activeTab</a></code> permission.</strong>
 273   </td>
 274 </tr>
 275 <tr>
 276   <td style="font-weight:bold">
 277     <!-- IDS_EXTENSION_PROMPT_WARNING_?_HOST -->
 278     <!-- IDS_EXTENSION_PROMPT_WARNING_4_OR_MORE_HOSTS -->
 279     Read and modify your data on <em>{list of websites}</em>
 280   </td>
 281   <td>
 282     A match pattern in the "permissions" field
 283     that specifies one or more hosts,
 284     but not all hosts
 285   </td>
 286   <td>
 287     <p>
 288     Up to 3 sites are listed by name.
 289     Subdomains aren't treated specially.
 290     For example, <code>a.com</code> and <code>b.a.com</code>
 291     are listed as different sites.
 292     </p>
 293
 294     <p>
 295     On autoupdate,
 296     the user sees a permission warning
 297     if the extension adds or changes sites.
 298     For example, going from <code>a.com,b.com</code>
 299     to <code>a.com,b.com,c.com</code>
 300     triggers a warning.
 301     Going from <code>b.a.com</code>
 302     to <code>a.com</code>,
 303     or vice versa,
 304     also triggers a warning.
 305     </p>
 306   </td>
 307 </tr>
 308
 309 <tr>
 310   <td style="font-weight:bold">
 311     <!-- IDS_EXTENSION_PROMPT_WARNING_MANAGEMENT -->
 312     Manage your apps, extensions, and themes
 313   </td>
 314   <td>
 315     "management" permission
 316   </td>
 317   <td>
 318     The "management" permission is required by the
 319     <a href="management"><code>chrome.management</code></a> module.
 320   </td>
 321 </tr>
 322
 323 <tr>
 324   <td style="font-weight:bold">
 325     <!-- IDS_EXTENSION_PROMPT_WARNING_MDNS -->
 326     Discover devices on your local network
 327   </td>
 328   <td>
 329     "mdns" permission
 330   </td>
 331   <td>
 332     The "mdns" permission is required by the
 333     <a href="mdns"><code>chrome.mdns</code></a> module.
 334   </td>
 335 </tr>
 336
 337 <tr>
 338   <td style="font-weight:bold">
 339     <!-- IDS_EXTENSION_PROMPT_WARNING_GEOLOCATION -->
 340     Detect your physical location
 341   </td>
 342   <td>
 343     "geolocation" permission
 344   </td>
 345   <td>
 346     Allows the extension to use the proposed HTML5
 347     <a href="http://dev.w3.org/geo/api/spec-source.html">geolocation API</a>
 348     without prompting the user for permission.
 349   </td>
 350 </tr>
 351
 352 <tr>
 353   <td style="font-weight:bold">
 354     <!-- IDS_EXTENSION_PROMPT_WARNING_CLIPBOARD-->
 355     Access data you copy and paste
 356   </td>
 357   <td>
 358     "clipboardRead" permission
 359   </td>
 360   <td>
 361     Allows the extension to use the following editing commands with
 362     <code>document.execCommand()</code>:
 363     <ul>
 364       <li> <code>"copy"</code> </li>
 365       <li> <code>"cut"</code> </li>
 366     </ul>
 367   </td>
 368 </tr>
 369
 370 <tr>
 371   <td style="font-weight:bold">
 372     <!-- IDS_EXTENSION_PROMPT_WARNING_PRIVACY-->
 373     Manipulate privacy-related settings
 374   </td>
 375   <td>
 376     "privacy" permission
 377   </td>
 378   <td>
 379     The "privacy" permission is required by the
 380     <a href="privacy"><code>chrome.privacy</code></a> module.
 381   </td>
 382 </tr>
 383
 384 <tr>
 385   <td style="font-weight:bold">
 386     <!-- IDS_EXTENSION_PROMPT_WARNING_SIGNED_IN_DEVICES-->
 387     Access the list of your signed-in devices
 388   </td>
 389   <td>
 390     "signedInDevices" permission
 391   </td>
 392   <td>
 393     The "signedInDevices" permission is required by the
 394     <a href="signedInDevices"><code>chrome.signedInDevices</code></a>
 395     module.
 396   </td>
 397 </tr>
 398
 399 <tr>
 400   <td style="font-weight:bold">
 401     <!-- IDS_EXTENSION_PROMPT_WARNING_TTS_ENGINE-->
 402     Access all text spoken using synthesized speech
 403   </td>
 404   <td>
 405     "ttsEngine" permission
 406   </td>
 407   <td>
 408     The "ttsEngine" permission is required by the
 409     <a href="ttsEngine"><code>chrome.ttsEngine</code></a> module.
 410   </td>
 411 </tr>
 412 </table>
 413 </p>
 414
 415
 416 <h2 id="nowarning"> Permissions that don't cause warnings </h2>
 417
 418 <p>
 419 The following permissions don't result in a warning:
 420 </p>
 421
 422 <ul>
 423   <li>"activeTab"</li>
 424 {{?is_apps}}
 425   <li>"app.window.alwaysOnTop"</li>
 426   <li>"app.window.fullscreen"</li>
 427   <li>"app.window.fullscreen.overrideEsc"</li>
 428   <li>"app.window.shape"</li>
 429 {{/is_apps}}
 430   <li>"browsingData"</li>
 431   <li>"chrome://favicon/"</li>
 432   <li>"clipboardWrite"</li>
 433   <li>"contextMenus"</li>
 434   <li>"cookies"</li>
 435   <li>"experimental"</li>
 436   <li>"idle"</li>
 437   <li>"notifications"</li>
 438 {{?is_apps}}
 439   <li>"pointerLock"</li>
 440 {{/is_apps}}
 441   <li>"storage"</li>
 442   <li>"unlimitedStorage"</li>
 443   <li>"webRequest"</li>
 444   <li>"webRequestBlocking"</li>
 445 </ul>
 446
 447 <h2 id="test"> Testing permission warnings </h2>
 448
 449 <p>
 450 If you'd like to see exactly which warnings your users will get,
 451 <a href="packaging">package your extension</a>
 452 into a <code>.crx</code> file,
 453 and install it.
 454 </p>
 455
 456 <p>
 457 To see the warnings users will get when your extension is autoupdated,
 458 you can go to a little more trouble
 459 and set up an autoupdate server.
 460 To do this, first create an update manifest
 461 and point to it from your extension,
 462 using the "update_url" key
 463 (see <a href="autoupdate">Autoupdating</a>).
 464 Next, <a href="packaging">package the extension</a>
 465 into a new <code>.crx</code> file,
 466 and install the app from this <code>.crx</code> file.
 467 Now, change the extension's manifest to contain the new permissions,
 468 and <a href="packaging#update">repackage the extension</a>.
 469 Finally, update the extension
 470 (and all other extensions that have outstanding updates)
 471 by clicking the <b>chrome://extensions</b> page's
 472 <b>Update extensions now</b> button.
 473 </p>
 474
 475 <h2 id="api">API</h2>
 476
 477 <p>
 478 You can get a list of permission warnings for any manifest with
 479 $(ref:management.getPermissionWarningsByManifest).
 480 </p>