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: concepts/connecting-external-content-deploy-teams.md
+90-54Lines changed: 90 additions & 54 deletions
Original file line number
Diff line number
Diff line change
@@ -11,24 +11,26 @@ ms.subservice: search
11
11
12
12
This article describes how to enable the simplified admin experience for your Microsoft Graph connector in the Teams admin center. When you enable this experience, Teams admins and Global admins can enable or disable your custom Microsoft Graph connector seamlessly in the Teams admin center.
13
13
14
-
14
+
15
15
16
16
To enable the simplified admin experience in the Teams admin center:
17
+
17
18
1. Update the Teams app manifest.
18
-
2. Update Microsoft Graph permissions.
19
-
3. Handle Microsoft Graph webhook notifications.
20
-
4. Create or delete Microsoft Graph connections.
21
-
5. Validate the experience by enabling the Microsoft Graph Connector in the Teams admin center.
19
+
1. Update Microsoft Graph permissions.
20
+
1. Handle Microsoft Graph webhook notifications.
21
+
1. Create or delete Microsoft Graph connections.
22
+
1. Validate the experience by enabling the Microsoft Graph Connector in the Teams admin center.
22
23
23
24
## Update the Teams app manifest
24
-
In the Teams app manifest, at the root, at the same level as properties like **name**, **description**, and **icons**, add the **graphConnector** property (introduced in [v1.11](https://developer.microsoft.com/en-us/json-schemas/teams/v1.11/MicrosoftTeams.schema.json) of the app manifest) with a **notificationUrl**. This field contains the URL to which Microsoft Graph connector notifications for the application are sent. The app manifest version must be [v1.13](https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json) or higher for the simplified admin experience to work.
25
+
26
+
In the Teams app manifest, at the root, at the same level as properties like **name**, **description**, and **icons**, add the **graphConnector** property (introduced in [v1.11](https://developer.microsoft.com/json-schemas/teams/v1.11/MicrosoftTeams.schema.json) of the app manifest) with a **notificationUrl**. This field contains the URL to which Microsoft Graph connector notifications for the application are sent. The app manifest version must be [v1.13](https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json) or higher for the simplified admin experience to work.
25
27
26
28
Ensure that the **webApplicationInfo** property is added to the manifest. After you update the manifest, upload it by sideloading the app or publishing the app to the store.
"id": "<AAD_APP_ID>", // e.g. "7e47846e-4bef-4c42-9817-a14e92287f28"
@@ -42,45 +44,74 @@ Ensure that the **webApplicationInfo** property is added to the manifest. After
42
44
```
43
45
44
46
## Update Microsoft Graph permissions
47
+
45
48
In the [Microsoft Entra admin center](https://entra.microsoft.com) > expand the **Identity** menu > select **Applications** > **App registrations** > select your app registration > select **API permissions** > select **Add a permission** > select **Microsoft Graph**. Select the `ExternalConnection.ReadWrite.OwnedBy` and `ExternalItem.ReadWrite.OwnedBy` Microsoft Graph permissions as shown in the following example.
46
-
49
+
50
+
47
51
48
52
## Handle Microsoft Graph webhook notifications
53
+
49
54
When the admin turns **on** or **off** the Microsoft Graph connector from the Teams admin center, Microsoft Graph sends a change notification to the URL specified in the **notificationUrl** property in the manifest. Your app needs to manage these Microsoft Graph connections accordingly.
50
55
51
56
### Change notifications
57
+
52
58
For details about how to set up change notifications, see [Set up notifications for changes in resource data](/graph/webhooks#change-notifications). The following example shows a payload.
53
59
54
-
To understand how to validate the inbound change notification, see [Validating the authenticity of notifications](/graph/webhooks-with-resource-data#validating-the-authenticity-of-notifications).
57
86
58
87
Keep the following tips in mind:
59
-
* You can ignore **SubscriptionExpirationDateTime** and **SubscriptionId**.
60
-
* The change notification is for Microsoft Graph connector management only when the @odata.type of the resource data matches the one in the sample payload.
61
-
* The **tenantId** identified is the customer's tenant ID. When calling the Microsoft Graph API to [manage Microsoft Graph connections](/graph/connecting-external-content-manage-connections), you must generate the app token on behalf of this customer's tenant ID.
62
-
* You can call the Microsoft Graph API to get the customer's display name and default domain name. This can help you map the **tenantId** to the unique identifier in your system. To learn more, see [find tenant information by tenant ID](/graph/api/tenantrelationship-findtenantinformationbytenantid).
63
-
* Within **resourceData**, use **state** to determine whether to create or delete connections. You need the **connectorsTicket** to create the connections.
88
+
89
+
- You can ignore `subscriptionExpirationDateTime` and `subscriptionId`.
90
+
- The change notification is for Microsoft Graph connector management only when the `@odata.type` of the resource data matches the one in the sample payload.
91
+
- The `tenantId` identified is the customer's tenant ID. When calling the Microsoft Graph API to [manage Microsoft Graph connections](connecting-external-content-manage-connections.md), you must generate the app token on behalf of this customer's tenant ID.
92
+
- You can call the Microsoft Graph API to get the customer's display name and default domain name. This can help you map the `tenantId` to the unique identifier in your system. To learn more, see [find tenant information by tenant ID](/graph/api/tenantrelationship-findtenantinformationbytenantid).
93
+
- Within `resourceData`, use `state` to determine whether to create or delete connections. You need the `connectorsTicket` to create the connections.
64
94
65
95
### Handling "connector enable" notification
66
96
67
97
To handle "connector enable" notifications:
68
98
69
-
* Determine which Microsoft Graph connections to create (how many connections and which schema for each connection) by using the [External connection List API](/graph/api/externalconnectors-externalconnection-list?view=graph-rest-beta&preserve-view=true&tabs=http) to query for all connections. Determine whether to create all connections from scratch, resume creation of connections (in resiliency flow), or no-op (when all desired connections are already in the **ready** state).
70
-
* The [connection](/graph/api/externalconnectors-external-post-connections) is created in a **draft** state. Pass the **connectorsTicket** opaque encoded string to the connection creation API in the `GraphConnectors-Ticket` HTTP header.
71
-
*[Register the schema](/graph/api/externalconnectors-externalconnection-patch-schema?view=graph-rest-beta&preserve-view=true&tabs=http).
72
-
* After a successful schema creation or update, the connection should reach a **ready** state.
99
+
- Determine which Microsoft Graph connections to create (how many connections and which schema for each connection) by using the [External connection List API](/graph/api/externalconnectors-externalconnection-list?view=graph-rest-beta&preserve-view=true&tabs=http) to query for all connections. Determine whether to create all connections from scratch, resume creation of connections (in resiliency flow), or no-op (when all desired connections are already in the **ready** state).
100
+
- The [connection](/graph/api/externalconnectors-external-post-connections) is created in a **draft** state. Pass the `connectorsTicket` opaque encoded string to the connection creation API in the `GraphConnectors-Ticket` HTTP header.
101
+
-[Register the schema](/graph/api/externalconnectors-externalconnection-patch-schema?view=graph-rest-beta&preserve-view=true&tabs=http).
102
+
- After a successful schema creation or update, the connection should reach a **ready** state.
73
103
74
104
### Handling "connector disable" notification
75
105
76
106
To handle "connector disable" notifications:
77
107
78
-
* Determine which Microsoft Graph connections to delete by using the [External connection List API](/graph/api/externalconnectors-externalconnection-list) to query for all connections.
79
-
* Delete all connections by using the [External connection Delete API](/graph/api/externalconnectors-externalconnection-delete?view=graph-rest-beta&preserve-view=true&tabs=http).
80
-
* We recommend that you build resiliency logic to retry the deleted connection to verify that it's deleted.
108
+
- Determine which Microsoft Graph connections to delete by using the [External connection List API](/graph/api/externalconnectors-externalconnection-list) to query for all connections.
109
+
- Delete all connections by using the [External connection Delete API](/graph/api/externalconnectors-externalconnection-delete?view=graph-rest-beta&preserve-view=true&tabs=http).
110
+
- We recommend that you build resiliency logic to retry the deleted connection to verify that it's deleted.
81
111
82
-
#### Request
83
-
```
112
+
### Example notification request
113
+
114
+
```http
84
115
POST https://example.com/notificationEndpoint
85
116
Content-type: application/json
86
117
Content-length: 100
@@ -107,27 +138,27 @@ Content-length: 100
107
138
}
108
139
```
109
140
110
-
#### Response
111
-
```
141
+
### 202 Response
142
+
143
+
```http
112
144
HTTP/1.1 202 Accepted
113
145
Content-type: application/json
114
146
Content-length: 0
115
147
```
148
+
116
149
You need to send a `202 - Accepted` status code in your response to Microsoft Graph. If Microsoft Graph doesn't receive a 2xx class code, it tries to publish the change notification a number of times for about four hours. After that, the change notification is dropped and isn't delivered.
117
150
118
-
>[!NOTE]
119
-
>Send the `202 - Accepted` status code as soon as you receive the change notification, even before you validate its authenticity. You are acknowledging the receipt of the change notification and preventing unnecessary retries.
120
-
>The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance.
121
-
>If the notification URL doesn't reply within 30 seconds for more than 10% of the requests from Microsoft Graph over a 10-minute period, all subsequent notifications will be delayed and retried for a period of 4 hours.
122
-
>If a notification URL doesn't reply within 30 seconds for more than 20% of the requests from Microsoft Graph over a 10-minute period, all subsequent notifications will be dropped.
151
+
> [!NOTE]
152
+
> Send the `202 - Accepted` status code as soon as you receive the change notification, even before you validate its authenticity. You are acknowledging the receipt of the change notification and preventing unnecessary retries. The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance. If the notification URL doesn't reply within 30 seconds for more than 10% of the requests from Microsoft Graph over a 10-minute period, all subsequent notifications will be delayed and retried for a period of 4 hours. If a notification URL doesn't reply within 30 seconds for more than 20% of the requests from Microsoft Graph over a 10-minute period, all subsequent notifications will be dropped.
153
+
154
+
To validate the authenticity of `validationToken`:
123
155
124
-
To validate the authenticity of **validatonToken**:
125
156
- Verify that the token hasn't expired.
126
157
- Verify that the token hasn't been tampered with and was issued by the Microsoft identity platform.
127
-
- Verify that the **azp** claim in the **validationToken** is **0bf30f3b-4a52-48df-9a82-234910c4a086**.
128
-
- Verify the **aud** claim in the **validationToken** is the same as the "{{Teams-appid}}" you specified.
158
+
- Verify that the `azp` claim in the token is **0bf30f3b-4a52-48df-9a82-234910c4a086**.
159
+
- Verify the `aud` claim in the token is the same as the "{{Teams-appid}}" you specified.
129
160
130
-
For details, see [Validating the authenticity of notification](/graph/webhooks-with-resource-data?tabs=csharp#validating-the-authenticity-of-notifications).
161
+
For details, see [Validating the authenticity of notification](/graph/webhooks-with-resource-data.md#validating-the-authenticity-of-notifications).
131
162
132
163
The following example shows a validation token.
133
164
@@ -137,7 +168,7 @@ The following example shows a validation token.
@@ -155,10 +186,12 @@ The following example shows a validation token.
155
186
```
156
187
157
188
## Create or delete Microsoft Graph connections
158
-
You need to send the **connectorTickets** from the payload you received as a `GraphConnectors-Ticket` header when you initiate the creation of the Teams app connection. The following example shows this process.
159
189
160
-
### Request
161
-
```
190
+
You need to send the `connectorTickets` from the payload you received as a `GraphConnectors-Ticket` header when you initiate the creation of the Teams app connection. The following example shows this process.
191
+
192
+
### Example create connector request
193
+
194
+
```http
162
195
POST https://graph.microsoft.com/v1.0/external/connection
>- You must set the {{connectorId}} to the value provided in the notification from Graph Connectors when you create the connection.
181
-
>- You should acquire the {{accessToken}} from the [Microsoft identity platform](/azure/active-directory/develop/v2-app-types) for the tenant that is being notified.
212
+
> [!NOTE]
213
+
>
214
+
> - You must set the {{connectorId}} to the value provided in the notification from Graph Connectors when you create the connection.
215
+
> - You should acquire the {{accessToken}} from the [Microsoft identity platform](/azure/active-directory/develop/v2-app-types) for the tenant that is being notified.
182
216
183
-
### Response
184
-
```
217
+
### Example create connector response
218
+
219
+
```http
185
220
HTTP/1.1 200 Accepted
186
221
Content-type: application/json
187
222
Content-length: 0
188
223
```
189
224
190
-
>[!NOTE]
191
-
>Various Microsoft 365 experiences can be enabled for the connections created. For details, see [Microsoft Graph connectors overview](/graph/connecting-external-content-connectors-overview).
225
+
>[!NOTE]
226
+
>Various Microsoft 365 experiences can be enabled for the connections created. For details, see [Microsoft Graph connectors overview](connecting-external-content-connectors-overview.md).
192
227
193
-
To learn how to ingest external items into a working Microsoft Graph connection, see [Create, update, and delete items added by your application via Microsoft Graph connectors](/graph/connecting-external-content-manage-items).
228
+
To learn how to ingest external items into a working Microsoft Graph connection, see [Create, update, and delete items added by your application via Microsoft Graph connectors](connecting-external-content-manage-items.md).
194
229
195
230
## Validate the experience by enabling the Microsoft Graph connector in the Teams admin center
196
231
197
232
To validate the experience:
198
-
* Sign in to the [Teams admin center](https://admin.teams.microsoft.com) as a Teams admin or Global admin of the tenant.
199
-
* Select the **Manage apps** blade in the left rail.
200
-
* Go to your Teams application.
201
-
* On the detail page of the Teams app, you notice a new **Graph Connector** tab that allows an admin to enable or disable the Microsoft Graph connector.
202
-
* Select the toggle button to send the enable or disable notifications to the notification endpoint of the app, as specified by the **graphConnector.notificationUrl** property in the app manifest.
233
+
234
+
- Sign in to the [Teams admin center](https://admin.teams.microsoft.com) as a Teams admin or Global admin of the tenant.
235
+
- Select the **Manage apps** blade in the left rail.
236
+
- Go to your Teams application.
237
+
- On the detail page of the Teams app, you notice a new **Graph Connector** tab that allows an admin to enable or disable the Microsoft Graph connector.
238
+
- Select the toggle button to send the enable or disable notifications to the notification endpoint of the app, as specified by the `graphConnector.notificationUrl` property in the app manifest.
203
239
204
240
## Make your Microsoft Graph connector available for other organizations in the Teams admin center
205
241
@@ -208,6 +244,7 @@ You can submit your Microsoft Graph connector packaged as a Teams app extended a
208
244
You can use the [step-by-step submission guide](/partner-center/marketplace/add-in-submission-guide) to learn how to submit your app. Make sure that you submit a **Teams app** in the **Microsoft 365 and Copilot** tab in **Marketplace offers**.
209
245
210
246
You need to submit a PDF in the **Additional certification info** step. Microsoft uses the information you provide in this PDF to make sure that your Microsoft Graph connector performs as expected in Copilot for Microsoft 365. Your PDF must have the following sections:
247
+
211
248
- Test accounts, license keys, and credentials
212
249
- Custom Vertical Name
213
250
- Semantic Labels
@@ -217,8 +254,7 @@ You need to submit a PDF in the **Additional certification info** step. Microsof
217
254
218
255
### Test accounts, license keys, and credentials
219
256
220
-
Create a user account on your demo tenant that Microsoft can use to validate your Microsoft Graph connector. This can be done in the [Users section](https://admin.microsoft.com/Adminportal/Home?#/users/:/adduser) of the Microsoft 365 Admin Center.
221
-
Ensure that this new user account has a Copilot for Microsoft 365 license.
257
+
Create a user account on your demo tenant that Microsoft can use to validate your Microsoft Graph connector. This can be done in the [Users section](https://admin.microsoft.com/Adminportal/Home?#/users/:/adduser) of the Microsoft 365 Admin Center. Ensure that this new user account has a Copilot for Microsoft 365 license.
222
258
223
259
In this section of the PDF, provide the credentials and any applicable license keys for this new user account. This information is mandatory. To learn more about how to prepare the user account for validation, see [best practices for providing test notes](/microsoftteams/platform/concepts/deploy-and-publish/appsource/prepare/submission-checklist?tabs=desktop#compile-testing-instructions).
0 commit comments