Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[All Hosts] (security) updating permissions articles for unified mani… #4719

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
40 changes: 32 additions & 8 deletions docs/concepts/privacy-and-security.md
Original file line number Diff line number Diff line change
@@ -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
---

Expand Down Expand Up @@ -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 for Microsoft 365](#tab/jsonmanifest)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this now be "unified app manifest for Microsoft 365"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this now be "unified app manifest for Microsoft 365"?

I don't think so. Did I miss a memo?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I picked it up from Office Add-ins with the unified app manifest for Microsoft 365.

I see. That's an acceptable variant that's consistent with Marketing's directive to use a description instead of a brand name, but normally we leave the "app" out. There's no place where we include the "app" in a section or tab title.


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
<?xml version="1.0" encoding="utf-8"?>
Expand All @@ -144,12 +166,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">

... <!-- To keep permissions as the focus, not displaying other elements. -->
<Permissions>ReadDocument</Permissions>
...
... <!-- To keep permissions as the focus, not displaying other elements. -->
<Permissions>ReadDocument</Permissions>
...
</OfficeApp>
```

---

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.
Expand Down
Loading