Requesting permissions for API use in content and task pane apps

apps for Office

This topic describes the different permission levels that you can declare in your content or task pane app's manifest to specify the level of JavaScript API access your app requires for its features.

Last modified: March 07, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your content and task pane apps. Figure 1 shows the five levels of API permissions you can declare in your app's manifest.

Figure 1. The five-level permission model for content and task pane apps

Levels of permissions for task pane apps



These permissions specify the subset of the API that the app runtime will allow your content or task pane app to use when a user inserts, and then activates (trusts) your app. To declare the permission level your content or task pane app requires, specify one of the permission text values in the Permissions element of your app's manifest. The following example requests the WriteDocument permission, which will allow only methods that can write to (but not read) the document.

<Permissions>WriteDocument</Permissions>

As a best practice, you should request permissions based on the principle of least privilege. That is, you should request permission to access only the minimum subset of the API that your app requires to function correctly. For example, if your app needs only to read data in a user's document for its features, you should request no more than the ReadDocument permission.

The following table describes the subset of the JavaScript API that is enabled by each permission level.

Permission

Enabled subset of the API

Restricted

The methods of the Settings object, and the Document.getActiveViewAsync method.

This is the minimum permission level that can be requested by a content or task pane app.

ReadDocument

In addition to the API allowed by the Restricted permission, adds access to the API members necessary to read the document and manage bindings.

This includes the use of:

ReadAllDocument

In addition to the API allowed by the Restricted and ReadDocument permissions, allows the following additional access to document data:

  • The Document.getSelectedDataAsync and Document.getFileAsync methods can access the underlying OOXML code of the document (which in addition to the text may include formatting, links, embedded graphics, comments, revisions, and so forth).

WriteDocument

In addition to the API allowed by the Restricted permission, adds access to the following API members:

ReadWriteDocument

In addition to the API allowed by the Restricted, ReadDocument, ReadAllDocument, and WriteDocument permissions, includes access to all remaining API supported by content and task pane apps, including methods for subscribing to events.

You must declare the ReadWriteDocument permission to access these additional API members:

Show:
© 2014 Microsoft