From d44cf2fb97de07d26a9ec787955415ce28f40ef6 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Thu, 8 Aug 2024 19:26:17 -0700 Subject: [PATCH 1/7] [All Hosts] (security) updating permissions articles for unified manifest --- docs/concepts/privacy-and-security.md | 34 +++++++++-- ...pi-use-in-content-and-task-pane-add-ins.md | 58 ++++++++++++------- ...pport-for-task-pane-and-content-add-ins.md | 44 +++++++++----- 3 files changed, 98 insertions(+), 38 deletions(-) diff --git a/docs/concepts/privacy-and-security.md b/docs/concepts/privacy-and-security.md index 162d7d05b3..66c9bd5087 100644 --- a/docs/concepts/privacy-and-security.md +++ b/docs/concepts/privacy-and-security.md @@ -1,7 +1,7 @@ --- title: Privacy and security for Office Add-ins description: Learn about the privacy and security aspects of the Office Add-ins platform. -ms.date: 05/16/2024 +ms.date: 09/06/2024 ms.localizationpriority: medium --- @@ -129,13 +129,35 @@ Follow these general guidelines to support the security model of Office Add-ins, ### Request the necessary permissions -The add-in platform provides a permissions model that your add-in uses to declare the level of access to a user's data that it requires for its features. Each permission level corresponds to the subset of the JavaScript API for Office your add-in is allowed to use for its features. For example, the **WriteDocument** permission for content and task pane add-ins allows access to the [Document.setSelectedDataAsync](/javascript/api/office/office.document) method that lets an add-in write to the user's document, but doesn't allow access to any of the methods for reading data from the document. This permission level makes sense for add-ins that only need to write to a document, such as an add-in where the user can query for data to insert into their document. +The add-in platform provides a permissions model that your add-in uses to declare the level of access to a user's data that it requires for its features. Each permission level corresponds to the subset of the JavaScript API for Office your add-in is allowed to use for its features. For example, the **write document** permission for content and task pane add-ins allows access to the [Document.setSelectedDataAsync](/javascript/api/office/office.document) method that lets an add-in write to the user's document, but doesn't allow access to any of the methods for reading data from the document. This permission level makes sense for add-ins that only need to write to a document, such as an add-in where the user can query for data to insert into their document. -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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **ReadDocument** permission. (But, keep in mind that requesting insufficient permissions will result in the add-in platform blocking your add-in's use of some APIs and will generate errors at run time.) +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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **read document** permission. (But, keep in mind that requesting insufficient permissions will result in the add-in platform blocking your add-in's use of some APIs and will generate errors at run time.) -You specify permissions in the manifest of your add-in, as shown in the example in this section below, and end users can see the requested permission level of an add-in before they decide to install or activate the add-in for the first time. Additionally, Outlook add-ins that request the **ReadWriteMailbox** permission require explicit administrator privilege to install. +You specify permissions in the manifest of your add-in, as shown in the example in this section below, and end users can see the requested permission level of an add-in before they decide to install or activate the add-in for the first time. Additionally, Outlook add-ins that request the **read/write mailbox** permission require explicit administrator privilege to install. -The following example shows how a task pane add-in specifies the **ReadDocument** permission in its manifest. To keep permissions as the focus, other elements in the manifest aren't displayed. +To see an example of how to request permissions in the manifest, open the tab for the type of manifest your add-in uses. + +# [Unified manifest](#tab/jsonmanifest) + +The following example shows how a task pane add-in specifies the **read document** permission in its manifest. To keep permissions as the focus, other elements in the manifest aren't displayed. + +```json +"authorization": { + "permissions": { + "resourceSpecific": [ + ... + { + "name": "Document.Read.User", + "type": "Delegated" + }, + ] + } +} +``` + +# [Add-in only manifest](#tab/xmlmanifest) + +The following example shows how a task pane add-in specifies the **read document** permission in its manifest. To keep permissions as the focus, other elements in the manifest aren't displayed. ```xml @@ -150,6 +172,8 @@ The following example shows how a task pane add-in specifies the **ReadDocument* ``` +--- + For more information about permissions for task pane and content add-ins, see [Requesting permissions for API use in add-ins](../develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md). For more information about permissions for Outlook add-ins, see the following topics. diff --git a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md index 8265c30b90..e02df24350 100644 --- a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md +++ b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md @@ -1,42 +1,60 @@ --- title: Requesting permissions for API use in add-ins -description: Learn about different permission levels to declare in the manifest of a content or task pane add-in to specify the level of JavaScript API access. -ms.date: 05/18/2023 +description: Learn about different permission levels to declare in the manifest of an add-in to specify the level of JavaScript API access. +ms.date: 09/06/2024 ms.localizationpriority: medium --- # Requesting permissions for API use in add-ins -This article describes the different permission levels that you can declare in your content or task pane add-in's manifest to specify the level of JavaScript API access your add-in requires for its features. +This article describes the different permission levels that you declare in your add-in's manifest to specify the level of JavaScript API access your add-in requires for its features. -> [!NOTE] -> To learn about permission levels for mail (Outlook) add-ins, see [Outlook permissions model](../outlook/privacy-and-security.md#permissions-model). +> [!IMPORTANT] +> This article applies to only non-Outlook add-ins. To learn about permission levels for Outlook add-ins, see [Outlook permissions model](../outlook/privacy-and-security.md#permissions-model). ## Permissions model -A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your content and task pane add-ins. Figure 1 shows the five levels of API permissions you can declare in your add-in's manifest. +A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. Figure 1 shows the five levels of API permissions you can declare in your add-in's manifest. -*Figure 1. The five-level permission model for content and task pane add-ins* +*Figure 1. The five-level permission model for add-ins* -![Levels of permissions for task pane apps.](../images/office15-app-sdk-task-pane-app-permission.png) +![Levels of permissions for add-ins.](../images/office15-app-sdk-task-pane-app-permission.png) -These permissions specify the subset of the API that the add-in [runtime](../testing/runtimes.md) will allow your content or task pane add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your content or task pane add-in requires, specify one of the permission text values in the [Permissions](/javascript/api/manifest/permissions) element of your add-in's manifest. The following example requests the **WriteDocument** permission, which will allow only methods that can write to (but not read) the document. +These permissions specify the subset of the API that the add-in [runtime](../testing/runtimes.md) allows your add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your add-in requires, specify one of the permission values in the manifest. The markup varies depending on the type of manifest. -```XML -WriteDocument -``` +- **Unified manifest for Microsoft 365**: Use the "authorization.permissions.resourceSpecific" property. The following example requests the **write document** permission, which allows only methods that can write to (but not read) the document. -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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **ReadDocument** permission. + ```json + "authorization": { + "permissions": { + "resourceSpecific": [ + ... + { + "name": "Document.Write.User", + "type": "Delegated" + }, + ] + } + }, + ``` + +- **Add-in only manifest**: Use the [Permissions](/javascript/api/manifest/permissions) element of the manifest. The following example requests the **write document** permission, which allows only methods that can write to (but not read) the document. + + ```XML + WriteDocument + ``` + +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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **read document** 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](/javascript/api/office/office.settings) object, and the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method. This is the minimum permission level that can be requested by a content or task pane add-in.| -|**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.
| -|**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 add-ins, including methods for subscribing to events. You must declare the **ReadWriteDocument** permission to access these additional API members:
| +|Permission canonical name|add-in only manifest name|unified manifest name|Enabled subset of the API| +|:-----|:-----|:-----|:-----| +|**restricted**|Restricted|Document.Restricted.User|The methods of the [Settings](/javascript/api/office/office.settings) object, and the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method. This is the minimum permission level that can be requested by an add-in.| +|**read document**|ReadDocument|Document.Read.User|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:
| +|**read all document**|ReadAllDocument|Document.ReadAll.User|In addition to the API allowed by the **Restricted** and **ReadDocument** permissions, allows the following additional access to document data.
| +|**write document**|WriteDocument|Document.Write.User|In addition to the API allowed by the **Restricted** permission, adds access to the following API members.
| +|**read/write document**|ReadWriteDocument|Document.ReadWrite.User|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 add-ins, including methods for subscribing to events. You must declare the **ReadWriteDocument** permission to access these additional API members:
| ## See also diff --git a/docs/develop/support-for-task-pane-and-content-add-ins.md b/docs/develop/support-for-task-pane-and-content-add-ins.md index 0c51bd26cd..30115856cf 100644 --- a/docs/develop/support-for-task-pane-and-content-add-ins.md +++ b/docs/develop/support-for-task-pane-and-content-add-ins.md @@ -120,19 +120,37 @@ For more details about working with custom data using the methods of the `Settin ## Permissions model and governance -Your add-in uses the `Permissions` element in its manifest to request permission to access the level of functionality it requires from the Office JavaScript API. For example, if your add-in requires read/write access to the document, its manifest must specify `ReadWriteDocument` as the text value in its `Permissions` element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the **ReadDocument** permission in a task pane's manifest. - -```XML - - -??? - ReadDocument -??? - - -``` +Your add-in uses the app manifest to request permission to access the level of functionality it requires from the Office JavaScript API. The method varies depending on the type of manifest. + +- **Unified manifest for Microsoft 365**: Use the "authorization.permissions.resourceSpecific" property. For example, if your add-in requires read/write access to the document, its manifest must specify `Document.ReadWrite.User` as the value in its "authorization.permissions.resourceSpecific.name" property.The following example requests the **read document** permission, which allows only methods that can write to (but not read) the document. + + ```json + "authorization": { + "permissions": { + "resourceSpecific": [ + ... + { + "name": "Document.Read.User", + "type": "Delegated" + }, + ] + } + }, + ``` + + +- **Add-in only manifest**: Use the `Permissions` element in its manifest For example, if your add-in requires read/write access to the document, its manifest must specify `ReadWriteDocument` as the text value in its `Permissions` element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the **read document** permission in a task pane's manifest. + + ```XML + + + + ReadDocument + ... + + ``` For more information, see [Requesting permissions for API use in add-ins](requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md). From ce5ffbf5a02851d558e339905fc47f886eada35a Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Thu, 8 Aug 2024 19:45:49 -0700 Subject: [PATCH 2/7] small fixes --- docs/concepts/privacy-and-security.md | 6 +++--- docs/develop/support-for-task-pane-and-content-add-ins.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/concepts/privacy-and-security.md b/docs/concepts/privacy-and-security.md index 66c9bd5087..5e85406072 100644 --- a/docs/concepts/privacy-and-security.md +++ b/docs/concepts/privacy-and-security.md @@ -137,7 +137,7 @@ You specify permissions in the manifest of your add-in, as shown in the example To see an example of how to request permissions in the manifest, open the tab for the type of manifest your add-in uses. -# [Unified manifest](#tab/jsonmanifest) +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) The following example shows how a task pane add-in specifies the **read document** permission in its manifest. To keep permissions as the focus, other elements in the manifest aren't displayed. @@ -166,9 +166,9 @@ The following example shows how a task pane add-in specifies the **read document xmlns:ver="http://schemas.microsoft.com/office/appforoffice/1.0" xsi:type="TaskPaneApp"> -... + ... ReadDocument -... + ... ``` diff --git a/docs/develop/support-for-task-pane-and-content-add-ins.md b/docs/develop/support-for-task-pane-and-content-add-ins.md index 30115856cf..48d25d2667 100644 --- a/docs/develop/support-for-task-pane-and-content-add-ins.md +++ b/docs/develop/support-for-task-pane-and-content-add-ins.md @@ -1,7 +1,7 @@ --- title: Office JavaScript API support for content and task pane add-ins description: Use the Office JavaScript API to create a task pane or content add-in. -ms.date: 03/21/2023 +ms.date: 09/06/2024 ms.localizationpriority: medium --- @@ -139,7 +139,7 @@ Your add-in uses the app manifest to request permission to access the level of f ``` -- **Add-in only manifest**: Use the `Permissions` element in its manifest For example, if your add-in requires read/write access to the document, its manifest must specify `ReadWriteDocument` as the text value in its `Permissions` element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the **read document** permission in a task pane's manifest. +- **Add-in only manifest**: Use the `Permissions` element in the manifest For example, if your add-in requires read/write access to the document, its manifest must specify `ReadWriteDocument` as the text value in its `Permissions` element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the **read document** permission in a task pane's manifest. ```XML From b1ee636a190b9b5d187fbfa370d35193b71f5dc0 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 9 Aug 2024 11:42:50 -0700 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com> --- docs/concepts/privacy-and-security.md | 2 +- ...for-api-use-in-content-and-task-pane-add-ins.md | 14 +++++++------- .../support-for-task-pane-and-content-add-ins.md | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/concepts/privacy-and-security.md b/docs/concepts/privacy-and-security.md index 5e85406072..6c38a0d519 100644 --- a/docs/concepts/privacy-and-security.md +++ b/docs/concepts/privacy-and-security.md @@ -167,7 +167,7 @@ The following example shows how a task pane add-in specifies the **read document xsi:type="TaskPaneApp"> ... - ReadDocument + ReadDocument ... ``` diff --git a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md index e02df24350..c011b31041 100644 --- a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md +++ b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md @@ -14,7 +14,7 @@ This article describes the different permission levels that you declare in your ## Permissions model -A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. Figure 1 shows the five levels of API permissions you can declare in your add-in's manifest. +A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. The following figure shows the five levels of API permissions you can declare in your add-in's manifest. *Figure 1. The five-level permission model for add-ins* @@ -44,17 +44,17 @@ These permissions specify the subset of the API that the add-in [runtime](../tes WriteDocument ``` -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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **read document** permission. +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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **read document** permission. The following table describes the subset of the JavaScript API that is enabled by each permission level. -|Permission canonical name|add-in only manifest name|unified manifest name|Enabled subset of the API| +|Permission canonical name|Add-in only manifest name|Unified manifest name|Enabled subset of the API| |:-----|:-----|:-----|:-----| |**restricted**|Restricted|Document.Restricted.User|The methods of the [Settings](/javascript/api/office/office.settings) object, and the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method. This is the minimum permission level that can be requested by an add-in.| -|**read document**|ReadDocument|Document.Read.User|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:
| -|**read all document**|ReadAllDocument|Document.ReadAll.User|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).

| -|**write document**|WriteDocument|Document.Write.User|In addition to the API allowed by the **Restricted** permission, adds access to the following API members.
| -|**read/write document**|ReadWriteDocument|Document.ReadWrite.User|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 add-ins, including methods for subscribing to events. You must declare the **ReadWriteDocument** permission to access these additional API members:
| +|**read document**|ReadDocument|Document.Read.User|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:
  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document.
  • The [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) method to get all of the text in the document, but not the underlying OOXML binary copy of the document
  • The [Binding.getDataAsync](/javascript/api/office/office.binding#office-office-binding-getdataasync-member(1)) method for reading bound data in the document.
  • The [addFromNamedItemAsync](/javascript/api/office/office.binding#office-office-bindings-addfromnameditemasync-member(1)), [addFromPromptAsync](/javascript/api/office/office.binding#office-office-bindings-addfrompromptasync-member(1)), and [addFromSelectionAsync](/javascript/api/office/office.binding#office-office-bindings-addfromselectionasync-member(1)) methods of the Bindings object for creating bindings in the document.
  • The [getAllAsync](/javascript/api/office/office.binding#office-office-bindings-getallasync-member(1)), [getByIdAsync](/javascript/api/office/office.binding#office-office-bindings-getbyidasync-member(1)), and [releaseByIdAsync](/javascript/api/office/office.binding#office-office-bindings-releasebyidasync-member(1)) methods of the Bindings object for accessing and removing bindings in the document.
  • The [Document.getFilePropertiesAsync](/javascript/api/office/office.document#office-office-document-getfilepropertiesasync-member(1)) method to access document file properties, such as the URL of the document.

  • The [Document.goToByIdAsync](/javascript/api/office/office.document#office-office-document-gotobyidasync-member(1)) method to navigate to named objects and locations in the document.

  • For task pane add-ins for Project, all of the "get" methods of the [ProjectDocument](/javascript/api/office/office.document) object.
| +|**read all document**|ReadAllDocument|Document.ReadAll.User|In addition to the API allowed by the **restricted** and **read document** permissions, allows the following additional access to document data.

  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) and [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) 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).

| +|**write document**|WriteDocument|Document.Write.User|In addition to the API allowed by the **restricted** permission, adds access to the following API members.
  • The [Document.setSelectedDataAsync](/javascript/api/office/office.document#office-office-document-setselecteddataasync-member(1)) method to write to the user's selection in the document.
| +|**read/write document**|ReadWriteDocument|Document.ReadWrite.User|In addition to the API allowed by the **restricted**, **read document**, **read all document**, and **write document** permissions, includes access to all remaining API supported by add-ins, including methods for subscribing to events. You must declare the **read/write document** permission to access these additional API members:

  • The [Binding.setDataAsync](/javascript/api/office/office.binding#office-office-binding-setdataasync-member(1)) method for writing to bound regions of the document

  • The [TableBinding.addRowsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addrowsasync-member(1)) method for adding rows to bound tables.
  • The [TableBinding.addColumnsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addcolumnsasync-member(1)) method for adding columns to bound tables.
  • The [TableBinding.deleteAllDataValuesAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-deletealldatavaluesasync-member(1)) method for deleting all data in a bound table.
  • The [setFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-setformatsasync-member(1)), [clearFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-clearformatsasync-member(1)), and [setTableOptionsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-settableoptionsasync-member(1)) methods of the TableBinding object for setting formatting and options on bound tables.
  • All of the members of the [CustomXmlNode](/javascript/api/office/office.customxmlnode), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [CustomXmlParts](/javascript/api/office/office.customxmlparts), and [CustomXmlPrefixMappings](/javascript/api/office/office.customxmlprefixmappings) objects
  • All of the methods for subscribing to the events supported by add-ins, specifically the `addHandlerAsync` and `removeHandlerAsync` methods of the [Binding](/javascript/api/office/office.binding), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [Document](/javascript/api/office/office.document), [ProjectDocument](/javascript/api/office/office.document), and [Settings](/javascript/api/office/office.document#office-office-document-settings-member) objects.
| ## See also diff --git a/docs/develop/support-for-task-pane-and-content-add-ins.md b/docs/develop/support-for-task-pane-and-content-add-ins.md index 48d25d2667..0792d94d62 100644 --- a/docs/develop/support-for-task-pane-and-content-add-ins.md +++ b/docs/develop/support-for-task-pane-and-content-add-ins.md @@ -122,7 +122,7 @@ For more details about working with custom data using the methods of the `Settin Your add-in uses the app manifest to request permission to access the level of functionality it requires from the Office JavaScript API. The method varies depending on the type of manifest. -- **Unified manifest for Microsoft 365**: Use the "authorization.permissions.resourceSpecific" property. For example, if your add-in requires read/write access to the document, its manifest must specify `Document.ReadWrite.User` as the value in its "authorization.permissions.resourceSpecific.name" property.The following example requests the **read document** permission, which allows only methods that can write to (but not read) the document. +- **Unified manifest for Microsoft 365**: Use the "authorization.permissions.resourceSpecific" property. For example, if your add-in requires read/write access to the document, its manifest must specify `Document.ReadWrite.User` as the value in its "authorization.permissions.resourceSpecific.name" property. The following example requests the **read document** permission, which allows only methods that can read (but not write to) the document. ```json "authorization": { From 1e3a9c4c235e4efc59acd35afd64b0639d1ab786 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 9 Aug 2024 11:44:18 -0700 Subject: [PATCH 4/7] Update docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md --- ...g-permissions-for-api-use-in-content-and-task-pane-add-ins.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md index c011b31041..0594c67d5e 100644 --- a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md +++ b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md @@ -16,7 +16,6 @@ This article describes the different permission levels that you declare in your A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. The following figure shows the five levels of API permissions you can declare in your add-in's manifest. -*Figure 1. The five-level permission model for add-ins* ![Levels of permissions for add-ins.](../images/office15-app-sdk-task-pane-app-permission.png) From b855e36cc7f9d98be37da115bd227745926ae219 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Mon, 19 Aug 2024 12:08:55 -0700 Subject: [PATCH 5/7] add column for app-specific APIs --- ...api-use-in-content-and-task-pane-add-ins.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md index 0594c67d5e..6e9ab4d756 100644 --- a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md +++ b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md @@ -45,15 +45,15 @@ These permissions specify the subset of the API that the add-in [runtime](../tes 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 add-in requires to function correctly. For example, if your add-in needs only to read data in a user's document for its features, you should request no more than the **read document** permission. -The following table describes the subset of the JavaScript API that is enabled by each permission level. - -|Permission canonical name|Add-in only manifest name|Unified manifest name|Enabled subset of the API| -|:-----|:-----|:-----|:-----| -|**restricted**|Restricted|Document.Restricted.User|The methods of the [Settings](/javascript/api/office/office.settings) object, and the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method. This is the minimum permission level that can be requested by an add-in.| -|**read document**|ReadDocument|Document.Read.User|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:
  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document.
  • The [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) method to get all of the text in the document, but not the underlying OOXML binary copy of the document
  • The [Binding.getDataAsync](/javascript/api/office/office.binding#office-office-binding-getdataasync-member(1)) method for reading bound data in the document.
  • The [addFromNamedItemAsync](/javascript/api/office/office.binding#office-office-bindings-addfromnameditemasync-member(1)), [addFromPromptAsync](/javascript/api/office/office.binding#office-office-bindings-addfrompromptasync-member(1)), and [addFromSelectionAsync](/javascript/api/office/office.binding#office-office-bindings-addfromselectionasync-member(1)) methods of the Bindings object for creating bindings in the document.
  • The [getAllAsync](/javascript/api/office/office.binding#office-office-bindings-getallasync-member(1)), [getByIdAsync](/javascript/api/office/office.binding#office-office-bindings-getbyidasync-member(1)), and [releaseByIdAsync](/javascript/api/office/office.binding#office-office-bindings-releasebyidasync-member(1)) methods of the Bindings object for accessing and removing bindings in the document.
  • The [Document.getFilePropertiesAsync](/javascript/api/office/office.document#office-office-document-getfilepropertiesasync-member(1)) method to access document file properties, such as the URL of the document.

  • The [Document.goToByIdAsync](/javascript/api/office/office.document#office-office-document-gotobyidasync-member(1)) method to navigate to named objects and locations in the document.

  • For task pane add-ins for Project, all of the "get" methods of the [ProjectDocument](/javascript/api/office/office.document) object.
| -|**read all document**|ReadAllDocument|Document.ReadAll.User|In addition to the API allowed by the **restricted** and **read document** permissions, allows the following additional access to document data.

  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) and [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) 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).

| -|**write document**|WriteDocument|Document.Write.User|In addition to the API allowed by the **restricted** permission, adds access to the following API members.
  • The [Document.setSelectedDataAsync](/javascript/api/office/office.document#office-office-document-setselecteddataasync-member(1)) method to write to the user's selection in the document.
| -|**read/write document**|ReadWriteDocument|Document.ReadWrite.User|In addition to the API allowed by the **restricted**, **read document**, **read all document**, and **write document** permissions, includes access to all remaining API supported by add-ins, including methods for subscribing to events. You must declare the **read/write document** permission to access these additional API members:

  • The [Binding.setDataAsync](/javascript/api/office/office.binding#office-office-binding-setdataasync-member(1)) method for writing to bound regions of the document

  • The [TableBinding.addRowsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addrowsasync-member(1)) method for adding rows to bound tables.
  • The [TableBinding.addColumnsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addcolumnsasync-member(1)) method for adding columns to bound tables.
  • The [TableBinding.deleteAllDataValuesAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-deletealldatavaluesasync-member(1)) method for deleting all data in a bound table.
  • The [setFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-setformatsasync-member(1)), [clearFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-clearformatsasync-member(1)), and [setTableOptionsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-settableoptionsasync-member(1)) methods of the TableBinding object for setting formatting and options on bound tables.
  • All of the members of the [CustomXmlNode](/javascript/api/office/office.customxmlnode), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [CustomXmlParts](/javascript/api/office/office.customxmlparts), and [CustomXmlPrefixMappings](/javascript/api/office/office.customxmlprefixmappings) objects
  • All of the methods for subscribing to the events supported by add-ins, specifically the `addHandlerAsync` and `removeHandlerAsync` methods of the [Binding](/javascript/api/office/office.binding), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [Document](/javascript/api/office/office.document), [ProjectDocument](/javascript/api/office/office.document), and [Settings](/javascript/api/office/office.document#office-office-document-settings-member) objects.
| +The following table describes the subsets of the [Common and Application-specific JavaScript APIs](understanding-the-javascript-api-for-office.md#api-models) that are enabled by each permission level. + +|Permission canonical name|Add-in only manifest name|Unified manifest name|Enabled subset of the Application-specific APIs|Enabled subset of the Common APIs| +|:-----|:-----|:-----|:-----|:-----| +|**restricted**|Restricted|Document.Restricted.User|None|The methods of the [Settings](/javascript/api/office/office.settings) object, and the [Document.getActiveViewAsync](/javascript/api/office/office.document#office-office-document-getactiveviewasync-member(1)) method. This is the minimum permission level that can be requested by an add-in.| +|**read document**|ReadDocument|Document.Read.User|All and only APIs that read the document or its properties.|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:
  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) method to get the selected text, HTML (Word only), or tabular data, but not the underlying Open Office XML (OOXML) code that contains all of the data in the document.
  • The [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) method to get all of the text in the document, but not the underlying OOXML binary copy of the document
  • The [Binding.getDataAsync](/javascript/api/office/office.binding#office-office-binding-getdataasync-member(1)) method for reading bound data in the document.
  • The [addFromNamedItemAsync](/javascript/api/office/office.binding#office-office-bindings-addfromnameditemasync-member(1)), [addFromPromptAsync](/javascript/api/office/office.binding#office-office-bindings-addfrompromptasync-member(1)), and [addFromSelectionAsync](/javascript/api/office/office.binding#office-office-bindings-addfromselectionasync-member(1)) methods of the Bindings object for creating bindings in the document.
  • The [getAllAsync](/javascript/api/office/office.binding#office-office-bindings-getallasync-member(1)), [getByIdAsync](/javascript/api/office/office.binding#office-office-bindings-getbyidasync-member(1)), and [releaseByIdAsync](/javascript/api/office/office.binding#office-office-bindings-releasebyidasync-member(1)) methods of the Bindings object for accessing and removing bindings in the document.
  • The [Document.getFilePropertiesAsync](/javascript/api/office/office.document#office-office-document-getfilepropertiesasync-member(1)) method to access document file properties, such as the URL of the document.

  • The [Document.goToByIdAsync](/javascript/api/office/office.document#office-office-document-gotobyidasync-member(1)) method to navigate to named objects and locations in the document.

  • For task pane add-ins for Project, all of the "get" methods of the [ProjectDocument](/javascript/api/office/office.document) object.
| +|**read all document**|ReadAllDocument|Document.ReadAll.User|Same as **read document**.|In addition to the API allowed by the **restricted** and **read document** permissions, allows the following additional access to document data.

  • The [Document.getSelectedDataAsync](/javascript/api/office/office.document#office-office-document-getselecteddataasync-member(1)) and [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) 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).

| +|**write document**|WriteDocument|Document.Write.User|All and only APIs that write to the document or its properties.|In addition to the API allowed by the **restricted** permission, adds access to the following API members.
  • The [Document.setSelectedDataAsync](/javascript/api/office/office.document#office-office-document-setselecteddataasync-member(1)) method to write to the user's selection in the document.
| +|**read/write document**|ReadWriteDocument|Document.ReadWrite.User|All Application-specfic APIs, including those that subscribe to events.|In addition to the API allowed by the **restricted**, **read document**, **read all document**, and **write document** permissions, includes access to all remaining API supported by add-ins, including methods for subscribing to events. You must declare the **read/write document** permission to access these additional API members:

  • The [Binding.setDataAsync](/javascript/api/office/office.binding#office-office-binding-setdataasync-member(1)) method for writing to bound regions of the document

  • The [TableBinding.addRowsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addrowsasync-member(1)) method for adding rows to bound tables.
  • The [TableBinding.addColumnsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-addcolumnsasync-member(1)) method for adding columns to bound tables.
  • The [TableBinding.deleteAllDataValuesAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-deletealldatavaluesasync-member(1)) method for deleting all data in a bound table.
  • The [setFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-setformatsasync-member(1)), [clearFormatsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-clearformatsasync-member(1)), and [setTableOptionsAsync](/javascript/api/office/office.tablebinding#office-office-tablebinding-settableoptionsasync-member(1)) methods of the TableBinding object for setting formatting and options on bound tables.
  • All of the members of the [CustomXmlNode](/javascript/api/office/office.customxmlnode), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [CustomXmlParts](/javascript/api/office/office.customxmlparts), and [CustomXmlPrefixMappings](/javascript/api/office/office.customxmlprefixmappings) objects
  • All of the methods for subscribing to the events supported by add-ins, specifically the `addHandlerAsync` and `removeHandlerAsync` methods of the [Binding](/javascript/api/office/office.binding), [CustomXmlPart](/javascript/api/office/office.customxmlpart), [Document](/javascript/api/office/office.document), [ProjectDocument](/javascript/api/office/office.document), and [Settings](/javascript/api/office/office.document#office-office-document-settings-member) objects.
| ## See also From b2193a549db0acaef79752b64418144bc3b4010c Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Wed, 28 Aug 2024 13:39:02 -0700 Subject: [PATCH 6/7] add host support note --- docs/concepts/privacy-and-security.md | 2 ++ ...-permissions-for-api-use-in-content-and-task-pane-add-ins.md | 2 ++ docs/develop/support-for-task-pane-and-content-add-ins.md | 1 + docs/includes/unified-manifest-support-note.md | 2 ++ 4 files changed, 7 insertions(+) create mode 100644 docs/includes/unified-manifest-support-note.md diff --git a/docs/concepts/privacy-and-security.md b/docs/concepts/privacy-and-security.md index 6c38a0d519..5483fdc13d 100644 --- a/docs/concepts/privacy-and-security.md +++ b/docs/concepts/privacy-and-security.md @@ -139,6 +139,8 @@ To see an example of how to request permissions in the manifest, open the tab fo # [Unified manifest for Microsoft 365](#tab/jsonmanifest) +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + The following example shows how a task pane add-in specifies the **read document** permission in its manifest. To keep permissions as the focus, other elements in the manifest aren't displayed. ```json diff --git a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md index 6e9ab4d756..7417d92f53 100644 --- a/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md +++ b/docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md @@ -37,6 +37,8 @@ These permissions specify the subset of the API that the add-in [runtime](../tes }, ``` + [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + - **Add-in only manifest**: Use the [Permissions](/javascript/api/manifest/permissions) element of the manifest. The following example requests the **write document** permission, which allows only methods that can write to (but not read) the document. ```XML diff --git a/docs/develop/support-for-task-pane-and-content-add-ins.md b/docs/develop/support-for-task-pane-and-content-add-ins.md index 0792d94d62..df2f336972 100644 --- a/docs/develop/support-for-task-pane-and-content-add-ins.md +++ b/docs/develop/support-for-task-pane-and-content-add-ins.md @@ -138,6 +138,7 @@ Your add-in uses the app manifest to request permission to access the level of f }, ``` + [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] - **Add-in only manifest**: Use the `Permissions` element in the manifest For example, if your add-in requires read/write access to the document, its manifest must specify `ReadWriteDocument` as the text value in its `Permissions` element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the **read document** permission in a task pane's manifest. diff --git a/docs/includes/unified-manifest-support-note.md b/docs/includes/unified-manifest-support-note.md new file mode 100644 index 0000000000..2810e966df --- /dev/null +++ b/docs/includes/unified-manifest-support-note.md @@ -0,0 +1,2 @@ +> [!NOTE] +> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It is available only as a preview for Excel, PowerPoint, and Word add-ins. \ No newline at end of file From 31c1d653e71e05024629b0bf527b298d91b14b37 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Mon, 7 Oct 2024 14:32:53 -0700 Subject: [PATCH 7/7] Update unified-manifest-support-note.md --- docs/includes/unified-manifest-support-note.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/unified-manifest-support-note.md b/docs/includes/unified-manifest-support-note.md index 2810e966df..2221e62056 100644 --- a/docs/includes/unified-manifest-support-note.md +++ b/docs/includes/unified-manifest-support-note.md @@ -1,2 +1,2 @@ > [!NOTE] -> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It is available only as a preview for Excel, PowerPoint, and Word add-ins. \ No newline at end of file +> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It's available only as a preview for Excel, PowerPoint, and Word add-ins.