diff --git a/docs/concepts/privacy-and-security.md b/docs/concepts/privacy-and-security.md index 162d7d05b3..f61ff8e33c 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: 02/12/2025 ms.localizationpriority: medium --- @@ -129,13 +129,37 @@ 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 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 +"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 @@ -144,12 +168,14 @@ The following example shows how a task pane add-in specifies the **ReadDocument* xmlns:ver="http://schemas.microsoft.com/office/appforoffice/1.0" xsi:type="TaskPaneApp"> -... - ReadDocument -... + ... + 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..6a9913f3e2 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,61 @@ --- 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: 02/12/2025 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. 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 content and task pane 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" + }, + ] + } + }, + ``` -The following table describes the subset of the JavaScript API that is enabled by each permission level. + [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -|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:
| +- **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 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:| +|**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.| +|**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.| +|**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:| ## 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..2306f2d961 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: 02/12/2025 ms.localizationpriority: medium --- @@ -120,19 +120,38 @@ 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 read (but not write to) the document. + + ```json + "authorization": { + "permissions": { + "resourceSpecific": [ + ... + { + "name": "Document.Read.User", + "type": "Delegated" + }, + ] + } + }, + ``` + + [!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. + + ```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). 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.