Acrolinx improvements

Author: jasonjoh

concepts/change-notifications-with-resource-data.md

@@ -33,7 +33,7 @@ Rich notifications include the following resource data in the payload:
 
 ## Creating a subscription
 
-Rich notifications are set up in the same way as [basic change notifications](/graph/api/subscription-post-subscriptions), except you **must** specify the following additional properties:
+Rich notifications are set up in the same way as [basic change notifications](/graph/api/subscription-post-subscriptions), except you **must** specify the following properties:
 
 - **includeResourceData** which should be set to `true` to explicitly request resource data.
 - **encryptionCertificate** which contains only the public key that Microsoft Graph uses to encrypt the resource data it returns to your app. For security, Microsoft Graph encrypts the resource data returned in a rich notification. You must provide a public encryption key as part of creating the subscription. For more information on creating and managing encryption keys, see [Decrypting resource data from change notifications](#decrypting-resource-data-from-change-notifications).
@@ -108,7 +108,7 @@ In this section, you explore the following validation concepts:
 
 ### Validation tokens in the change notification
 
-A change notification with resource data contains an additional property, **validationTokens**, which contains an array of [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519) (JWT) generated by Microsoft Graph. Microsoft Graph generates a single token for each distinct app and tenant pair for whom there's an item in the **value** array. Keep in mind that change notifications might contain a mix of items for various apps and tenants that subscribed using the same **notificationUrl**.
+A change notification with resource data contains an extra property, **validationTokens**, which contains an array of [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519) (JWT) generated by Microsoft Graph. Microsoft Graph generates a single token for each distinct app and tenant pair for whom there's an item in the **value** array. Keep in mind that change notifications might contain a mix of items for various apps and tenants that subscribed using the same **notificationUrl**.
 
 > [!NOTE]
 > Microsoft Graph doesn't send validation tokens for [change notifications delivered through Azure Event Hubs](change-notifications-delivery.md) because the subscription service doesn't need to validate the **notificationUrl** for Event Hubs.
@@ -154,11 +154,11 @@ In particular, perform validation on every JWT token in the **validationTokens**
 
 Use the following steps to validate tokens and apps that generate tokens:
 
-1. Validate that the token hasn't expired.
+1. Validate that the token isn't expired.
 
-2. Validate the token hasn't been tampered with and was issued by the expected authority, Microsoft identity platform:
+2. Validate that the Microsoft identity platform issued the token and that the token isn't tampered with.
 
-    - Obtain the signing keys from the common configuration endpoint: `https://login.microsoftonline.com/common/.well-known/openid-configuration`. This configuration is cached by your app for some time. The configuration is updated frequently as signing keys are rotated daily.
+    - Obtain the signing keys from the common configuration endpoint: `https://login.microsoftonline.com/common/.well-known/openid-configuration`. Your app can cache this configuration for some time. The configuration is updated frequently as signing keys are rotated daily.
     - Verify the signature of the JWT token using those keys.
 
     Don't accept tokens issued by any other authority.
@@ -171,8 +171,8 @@ Use the following steps to validate tokens and apps that generate tokens:
 
 4. **Critical**: Validate that the app that generated the token represents the Microsoft Graph change notification publisher.
 
-    - Check that the **azp** property in the token matches the expected value of `0bf30f3b-4a52-48df-9a82-234910c4a086`.
-    - This ensures that change notifications aren't sent by a different app that isn't Microsoft Graph.
+    - Check that the `azp` property in the token matches the expected value of `0bf30f3b-4a52-48df-9a82-234910c4a086`.
+    - This check ensures that a different app that isn't Microsoft Graph did not send the change notifications.
 
 ### Example JWT token
 
@@ -260,7 +260,7 @@ private boolean IsValidationTokenValid(String[] appIds, String tenantId, String
 }
 ```
 
-For the Java sample to work, you'll also need to implement the `JwkKeyResolver`.
+For the Java sample to work, you also need to implement the `JwkKeyResolver`.
 
 ```java
 package com.example.restservice;
@@ -336,7 +336,7 @@ export function isTokenValid(token, appId, tenantId) {
 
 ## Decrypting resource data from change notifications
 
-The **resourceData** property of a change notification includes only the basic ID and type information of a resource instance. The **encryptedData** property contains the full resource data, encrypted by Microsoft Graph using the public key provided in the subscription. The property also contains values required for verification and decryption. This is done to increase the security of customer data accessed via change notifications. It is your responsibility to secure the private key to ensure that a third party can't decrypt the customer data, even if they manage to intercept the original change notifications.
+The **resourceData** property of a change notification includes only the basic ID and type information of a resource instance. The **encryptedData** property contains the full resource data, encrypted by Microsoft Graph using the public key provided in the subscription. The property also contains values required for verification and decryption. This encryption is done to increase the security of customer data accessed via change notifications. It is your responsibility to secure the private key to ensure that a third party can't decrypt the customer data, even if they manage to intercept the original change notifications.
 
 In this section, you learn the following concepts:
 
@@ -402,7 +402,7 @@ To decrypt resource data, your app should perform the reverse steps, using the p
 
 1. Use the symmetric key to calculate the HMAC-SHA256 signature of the value in **data**.
 
-    Compare it to the value in **dataSignature**. If they don't match, assume the payload has been tampered with and don't decrypt it.
+    Compare it to the value in **dataSignature**. If they don't match, assume the payload is tampered with and don't decrypt it.
 
 1. Use the symmetric key with an Advanced Encryption Standard (AES) (such as the .NET [Aes](/dotnet/api/system.security.cryptography.aes?view=netframework-4.8&preserve-view=true)) to decrypt the content in **data**.
 
@@ -416,7 +416,7 @@ To decrypt resource data, your app should perform the reverse steps, using the p
 
 ### Example: decrypting a notification with encrypted resource data
 
-The following JSON example shows a change notification that includes encrypted property values of a **chatMessage** instance in a channel message. The instance is specified by the `@odata.id` value.
+The following JSON example shows a change notification that includes encrypted property values of a **chatMessage** instance in a channel message. The `@odata.id` value specifies the instance.
 
 ```json
 {

concepts/connecting-external-content-deploy-teams.md

@@ -45,7 +45,7 @@ Ensure that the **webApplicationInfo** property is added to the manifest. After
 
 ## Update Microsoft Graph permissions
 
-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.
+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.
 
 ![Updated Microsoft Graph permissions](images/connectors-images/AADperms-TAC-connectors.png)
 
@@ -89,7 +89,7 @@ Keep the following tips in mind:
 - You can ignore `subscriptionExpirationDateTime` and `subscriptionId`.
 - 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.
 - 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.
-- 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).
+- You can call the Microsoft Graph API to get the customer's display name and default domain name. This step 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).
 - Within `resourceData`, use `state` to determine whether to create or delete connections. You need the `connectorsTicket` to create the connections.
 
 ### Handling "connector enable" notification
@@ -146,15 +146,15 @@ Content-type: application/json
 Content-length: 0
 ```
 
-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.
+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 many times for about four hours. After that, the change notification is dropped and isn't delivered.
 
 > [!NOTE]
 > 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.
 
 To validate the authenticity of `validationToken`:
 
-- Verify that the token hasn't expired.
-- Verify that the token hasn't been tampered with and was issued by the Microsoft identity platform.
+- Verify that the token isn't expired.
+- Verify that the Microsoft identity platform issued the token and that the token isn't tampered with.
 - Verify that the `azp` claim in the token is **0bf30f3b-4a52-48df-9a82-234910c4a086**.
 - Verify the `aud` claim in the token is the same as the "{{Teams-appid}}" you specified.
 
@@ -275,7 +275,7 @@ In the Sample Prompts section, provide two sample prompts that Microsoft can use
 
 ### Connection Description
 
-In Connection Description section, provide the `description` property for your custom Microsoft Graph connection. Microsoft will use this to ensure that your Microsoft Graph connection has a rich description for Copilot for Microsoft 365. This description is optional.
+In Connection Description section, provide the `description` property for your custom Microsoft Graph connection. Microsoft uses this to ensure that your Microsoft Graph connection has a rich description for Copilot for Microsoft 365. This description is optional.
 
 ### Activity Settings