You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/concepts/privacy-and-security.md
+34-8Lines changed: 34 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Privacy and security for Office Add-ins
3
3
description: Learn about the privacy and security aspects of the Office Add-ins platform.
4
-
ms.date: 05/16/2024
4
+
ms.date: 02/12/2025
5
5
ms.localizationpriority: medium
6
6
---
7
7
@@ -129,13 +129,37 @@ Follow these general guidelines to support the security model of Office Add-ins,
129
129
130
130
### Request the necessary permissions
131
131
132
-
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.
132
+
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.
133
133
134
-
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.)
134
+
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.)
135
135
136
-
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.
136
+
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.
137
137
138
-
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.
138
+
To see an example of how to request permissions in the manifest, open the tab for the type of manifest your add-in uses.
139
+
140
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
141
+
142
+
[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
143
+
144
+
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.
145
+
146
+
```json
147
+
"authorization": {
148
+
"permissions": {
149
+
"resourceSpecific": [
150
+
...
151
+
{
152
+
"name": "Document.Read.User",
153
+
"type": "Delegated"
154
+
},
155
+
]
156
+
}
157
+
}
158
+
```
159
+
160
+
# [Add-in only manifest](#tab/xmlmanifest)
161
+
162
+
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.
139
163
140
164
```xml
141
165
<?xml version="1.0" encoding="utf-8"?>
@@ -144,12 +168,14 @@ The following example shows how a task pane add-in specifies the **ReadDocument*
... <!-- To keep permissions as the focus, not displaying other elements. -->
148
-
<Permissions>ReadDocument</Permissions>
149
-
...
171
+
... <!-- To keep permissions as the focus, not displaying other elements. -->
172
+
<Permissions>ReadDocument</Permissions>
173
+
...
150
174
</OfficeApp>
151
175
```
152
176
177
+
---
178
+
153
179
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).
154
180
155
181
For more information about permissions for Outlook add-ins, see the following topics.
Copy file name to clipboardExpand all lines: docs/design/built-in-button-integration.md
+86-2Lines changed: 86 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Integrate built-in Office buttons into custom control groups and tabs
3
3
description: Learn how to include built-in Office buttons in your custom command groups and tabs on the Office ribbon.
4
-
ms.date: 06/26/2024
4
+
ms.date: 02/12/2025
5
5
ms.topic: how-to
6
6
ms.localizationpriority: medium
7
7
---
@@ -17,6 +17,88 @@ You can insert built-in Office buttons into your custom control groups on the Of
17
17
> [!IMPORTANT]
18
18
> The add-in feature described in this article is only available in **PowerPoint** on the web, on Windows, and on Mac.
19
19
20
+
Open the tab for the type of manifest your add-in uses for the details of the manifest markup.
21
+
22
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
23
+
24
+
[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
25
+
26
+
## Insert a built-in control group into a custom tab
27
+
28
+
To insert a built-in Office control group into a custom tab, add a group object with a "builtInGroupId" property *instead of an "id" property* to the "groups" array of your custom tab object. Set to the ID of the built-in group. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups). *The built-in group object should have no other properties.*
29
+
30
+
The following example adds the Office Paragraph control group to a custom tab.
31
+
32
+
33
+
```json
34
+
"extensions": [
35
+
...
36
+
{
37
+
...
38
+
"ribbons": [
39
+
...
40
+
{
41
+
...
42
+
"tabs": [
43
+
{
44
+
"id": "MyTab",
45
+
...
46
+
"groups": [
47
+
... // Optionally, other groups in the tab
48
+
{
49
+
"builtInGroupId": "Paragraph"
50
+
},
51
+
... // Optionally, other groups in the tab
52
+
]
53
+
}
54
+
]
55
+
}
56
+
]
57
+
}
58
+
]
59
+
```
60
+
61
+
## Insert a built-in control into a custom group
62
+
63
+
To insert a built-in Office control into a custom group, add a control object with a "builtInControlId" property *instead of an "id" property* to the "controls" array of your custom group object. Set to the ID of the built-in control. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups). *The built-in control object should have no other properties.*
64
+
65
+
The following example adds the Office Superscript control to a custom group.
66
+
67
+
```json
68
+
"extensions": [
69
+
...
70
+
{
71
+
...
72
+
"ribbons": [
73
+
...
74
+
{
75
+
...
76
+
"tabs": [
77
+
{
78
+
...
79
+
"groups": [
80
+
{
81
+
"id": "MyGroup",
82
+
...
83
+
"controls": [
84
+
... // Optionally, other controls in the group
85
+
{
86
+
"builtInControlId": "Superscript"
87
+
},
88
+
... // Optionally, other controls in the group
89
+
]
90
+
}
91
+
]
92
+
}
93
+
]
94
+
}
95
+
]
96
+
}
97
+
]
98
+
```
99
+
100
+
# [Add-in only manifest](#tab/xmlmanifest)
101
+
20
102
## Insert a built-in control group into a custom tab
21
103
22
104
To insert a built-in Office control group into a tab, add an [OfficeGroup](/javascript/api/manifest/customtab#officegroup) element as a child element in the parent **\<CustomTab\>** element. The `id` attribute of the of the **\<OfficeGroup\>** element is set to the ID of the built-in group. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups).
@@ -62,6 +144,8 @@ The following markup example adds the Office Superscript control to a custom gro
62
144
</ExtensionPoint>
63
145
```
64
146
147
+
---
148
+
65
149
> [!NOTE]
66
150
> Users can customize the ribbon in the Office application. Any user customizations will override your manifest settings. For example, a user can remove a button from any group and remove any group from a tab.
67
151
@@ -71,4 +155,4 @@ The IDs for supported controls and control groups are in files in the repo [Offi
71
155
72
156
## Behavior on unsupported platforms
73
157
74
-
If your add-in is installed on a platform that doesn't support [requirement set AddinCommands 1.3](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets), then the markup described in this article is ignored and the built-in Office controls/groups won't appear in your custom groups/tabs. To prevent your add-in from being installed on platforms that don't support the markup, add a reference to the requirement set in the **\<Requirements\>** section of the manifest. For instructions, see [Specify which Office versions and platforms can host your add-in](../develop/specify-office-hosts-and-api-requirements.md#specify-which-office-versions-and-platforms-can-host-your-add-in). Alternatively, design your add-in to have an experience when **AddinCommands 1.3** isn't supported, as described in [Design for alternate experiences](../develop/specify-office-hosts-and-api-requirements.md#design-for-alternate-experiences). For example, if your add-in contains instructions that assume the built-in buttons are in your custom groups, you could design a version that assumes that the built-in buttons are only in their usual places.
158
+
If your add-in is installed on a platform that doesn't support [requirement set AddinCommands 1.3](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets), then the markup described in this article is ignored and the built-in Office controls/groups won't appear in your custom groups/tabs. To prevent your add-in from being installed on platforms that don't support the markup, you must specify **AddinCommands 1.3** in the manifest as a requirement for installation. For instructions, see [Specify which Office versions and platforms can host your add-in](../develop/specify-office-hosts-and-api-requirements.md#specify-which-office-versions-and-platforms-can-host-your-add-in). Alternatively, design your add-in to have an experience when **AddinCommands 1.3** isn't supported, as described in [Design for alternate experiences](../develop/specify-office-hosts-and-api-requirements.md#design-for-alternate-experiences). For example, if your add-in contains instructions that assume the built-in buttons are in your custom groups, you could design a version that assumes that the built-in buttons are only in their usual places.
Copy file name to clipboardExpand all lines: docs/design/content-add-ins.md
+37-2Lines changed: 37 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Content Office Add-ins
3
3
description: Content add-ins are surfaces that can be embedded directly into Excel or PowerPoint documents that give users access to interface controls that run code to modify documents or display data from a data source.
4
-
ms.date: 06/27/2024
4
+
ms.date: 02/12/2025
5
5
ms.topic: overview
6
6
ms.localizationpriority: medium
7
7
---
@@ -41,11 +41,46 @@ For Mac, the personality menu measures 26x26 pixels, but floats 8 pixels in from
41
41
42
42
## Implementation
43
43
44
-
There are minor differences in the manifests between content add-ins and add-ins that use task panes.
44
+
There are minor differences in the manifests between content add-ins and add-ins that use task panes. Open the tab for the type of manifest you're using.
45
+
46
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
47
+
48
+
> [!NOTE]
49
+
> The unified manifest is available in Excel, PowerPoint, and Word as a developer preview. For Outlook, it's generally available and can be used in production add-ins.
50
+
51
+
Configure the manifest with the following steps.
52
+
53
+
1. Add a "contentRuntimes" child array to the extension object in the "extensions" array.
54
+
1. Remove the "runtimes" property if it is present. The "runtimes" array is for task pane or mail add-ins. These cannot be combined with a content add-in.
55
+
1. Add an anonymous content runtime object in the "contentRuntimes" array.
56
+
1. Set the "id" property of the object to a descriptive name.
57
+
1. Set the "code.page" object to the full URL of the custom content that you want to embed in the document.
58
+
1. Optionally, set the "requestedWidth" and "requestedHeight" properties to a size between 32 and 1000 pixels. If these properties aren't used, the Office application determines the size.
59
+
1. Optionally, set the "disableSnapshot" property to `true` to prevent Office from saving a snapshot of the content component with the document.
60
+
61
+
The following is an example of a "contentRuntimes" property.
62
+
63
+
```json
64
+
"contentRuntimes": [
65
+
{
66
+
"id": "ContentRuntime",
67
+
"code": {
68
+
"page": "https://localhost:3000/content.html"
69
+
},
70
+
"requestedWidth": 100,
71
+
"requestedHeight": 100,
72
+
"disableSnapshot": true,
73
+
}
74
+
]
75
+
```
76
+
77
+
# [XML Manifest](#tab/xmlmanifest)
45
78
46
79
- For the **\<[OfficeApp](/javascript/api/manifest/officeapp)\>** element, set the `xsi:type` attribute to `"ContentApp"`.
47
80
- In the **\<[DefaultSettings](/javascript/api/manifest/defaultsettings)\>** element, add the **\<[RequestedHeight](/javascript/api/manifest/requestedheight)\>** and **\<[RequestedWidth](/javascript/api/manifest/requestedwidth)\>** elements.
48
81
82
+
---
83
+
49
84
For a sample that implements a content add-in, see [Excel Content Add-in Humongous Insurance](https://github.com/OfficeDev/Excel-Content-Add-in-Humongous-Insurance) on GitHub.
50
85
51
86
To create your own content add-in, see the [Excel content add-in quick start](../quickstarts/excel-quickstart-content.md) and [PowerPoint content add-in quick start](../quickstarts/powerpoint-quickstart-content.md).
0 commit comments