update based on feeback from Acrolinx

Author: j-patrick

articles/cosmos-db/managed-identity-based-authentication.md

@@ -1,6 +1,6 @@
 ---
-title: Managed Identity based authentication with Azure Cosmos DB and Azure Active Directory
-description: Learn how to configure an Azure AD identity for msi-based authentication to access keys from Azure Cosmos DB.
+title: Managed Identity based authentication and authorization with Azure Cosmos DB and Azure Active Directory
+description: Learn how to configure an Azure AD identity  to access keys from Azure Cosmos DB.
 author: justipat
 ms.service: cosmos-db
 ms.topic: conceptual
@@ -12,33 +12,31 @@ ms.reviewer: sngun
 
 # Managed Identity based authentication and authorization with Azure Cosmos DB and Azure Active Directory
 
-Managed Identity authentication enables your client application to be authenticated by using Azure Active Directory (Azure AD). You can perform Managed Identity based authentication / authorization on any service that [supports system assigned identities](/articles/active-directory/managed-identities-azure-resources/services-support-managed-identities.md). The end result will be a service that can read Azure Cosmos DB keys without having the keys directly in the service. The solution outlined in this article also creates a **robust key rotation agnostic**  solution for cosmos key management. 
+In this article we'll setup a **robust, key rotation agnostic,** solution for Cosmos DB key management by leveraging [Managed Service Identities](/articles/active-directory/managed-identities-azure-resources/services-support-managed-identities.md). Though we're using an Azure Function for this example, this solution can be used with any service that [supports managed service identities](/articles/active-directory/managed-identities-azure-resources/services-support-managed-identities.md). 
 
-You will learn how to:
+You'll learn how to:
 
 * Assign a System Identity
 * Grant the System Identity access to your Cosmos DB
 * Write the code for robust Cosmos DB key management
 
-In the solution below we will be building an Azure Function that wakes up every hour to read a set of sale receipts from Cosmos DB and create an hourly summary of sales, storing it back into Cosmos DB.
+In the solution below, we'll be building an Azure Function that will handle summarizing the last hour of sales. The function will wake up every hour, and will read a set of sale receipts from Cosmos DB. Then the function will create an hourly summary of sales and store it back in the container. To simplify the scenario, cleanup of the already processed receipts will be handled by an already configured [TTL](./time-to-live.md) setting.
 
-Though we are using Azure Functions below this will work with all Azure Services that support [system managed identity](/articles/active-directory/managed-identities-azure-resources/services-support-managed-identities.md)
+## Assign a System Identity to an Azure Function
 
-## Assign a System Identity to the your Azure Function
-
-In this step, you will assign a managed system identity to your Azure Function.
+In this step, you'll assign a managed system identity to your Azure Function.
 
 1. Sign into the [Azure portal](https://portal.azure.com/)
 
 1. Open the Azure Function pane, and for your function app select the **Identity tab**: 
 ![Identity Tab](./media/managed-identity-based-authentication/identity-tab-selection.png)
 
-1. On the **Identity tab** switch **System Identity** to the "On" position. Be sure to click **Save**. You will be prompted to confirm you want to turn this on. Please accept. In the end the **System Identity** pane should look like this:  
+1. On the **Identity tab** switch **System Identity** to the "On" position. Be sure to click **Save**, and confirm you want to turn on System Identity. In the end the **System Identity** pane should look like this:  
 ![Managed System Identity turned on](./media/managed-identity-based-authentication/identity-tab-system-managed-on.png)
 
 ## Grant the System Identity Access to your Cosmos DB. 
 
-In this step, you will assign a role to the Azure Function's System Identity. Cosmos DB has multiple built in roles you can assign the System Identity too. For this exercise we will just focus on two:
+In this step, you'll assign a role to the Azure Function's System Identity. Cosmos DB has multiple built-in roles you can assign the System Identity too. For this exercise we'll just focus on two:
 
 |**Built-in role**  |**Description**  |
 |---------|---------|
@@ -49,11 +47,11 @@ In this step, you will assign a role to the Azure Function's System Identity. Co
 > RBAC support in Azure Cosmos DB applies to control plane operations only. Data plane operations are secured using master keys or resource tokens. To learn more, see [Secure access to data in Azure Cosmos DB](secure-access-to-data.md)
 
 > [!TIP] 
-> When assigning roles, only assign the needed access. So if your service only need to read, then only assign the Service Identity to **Cosmos DB Account Reader**. For more information on the importance of **least privilege access** please see [lower exposure of privileged accounts](/azure/security/fundamentals/identity-management-best-practices#lower-exposure-of-privileged-accounts).
+> When assigning roles, only assign the needed access. So if your service only need to read, then only assign the Service Identity to **Cosmos DB Account Reader**. For more information about the importance of **least privilege access,** see [lower exposure of privileged accounts](/azure/security/fundamentals/identity-management-best-practices#lower-exposure-of-privileged-accounts).
 
-For our scenario we need to be able to read the sale receipt documents summarize them and then write back that summary to Cosmos DB. We will use the **DocumentDB Account Contributor** role. 
+For our scenario, we'll read the sale receipt documents, summarize them, and then write back that summary to Cosmos DB. Since we need write access, we'll use the **DocumentDB Account Contributor** role. 
 
-1. Open your Cosmos DB in the portal, select the **Access Management (IAM) Pane**, and the the **Role Assignments** tab:
+1. Open your Cosmos DB in the portal, select the **Access Management (IAM) Pane**, and then the **Role Assignments** tab:
 ![IAM Pane](./media/managed-identity-based-authentication/cosmos-db-iam-tab.png)
 
 1. Select the **+ Add** button, then **add role assignment**:
@@ -71,12 +69,12 @@ For our scenario we need to be able to read the sale receipt documents summarize
 
 ## Programmatically access the Cosmos DB keys from the Azure Function
 
-Now we have a function app that has a system managed identity. That identity is given the **DocumentDB Account Contributor** role in the Cosmos DB permissions. The code below will run on the **Function App** and will get the keys and create a CosmosClient. Then perform the the summarization business logic.
+Now we have a function app that has a system managed identity. That identity is given the **DocumentDB Account Contributor** role in the Cosmos DB permissions. The **Function App** code below will get the needed Cosmos DB Keys, create a CosmosClient, and run the summarization business logic.
 
-The api we will be using to get the Cosmos DB Keys is the [List Keys API](https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListKeys).
+We'll be using to get the Cosmos DB Keys is the [List Keys API](https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListKeys).
 
 
-The api returns DatabaseAccountListKeysResult. This type is not defined in the C# libraries, but it is easy to implement. The follow is an implementation for this class. Add it to the solution: 
+The api returns DatabaseAccountListKeysResult. This type isn't defined in the C# libraries. The code below is an implementation for this class. Add it to the solution: 
 ```csharp 
 namespace SummarizationService 
 {
@@ -90,7 +88,7 @@ namespace SummarizationService
 }
 ```
 
-The library we will use to get our Service Managed token is [Microsoft.Azure.Services.AppAuthentication](https://www.nuget.org/packages/Microsoft.Azure.Services.AppAuthentication). You can find other ways to get the token and more information about the Microsoft.Azure.Service.AppAuthentication library by reading up on  [Service To Service Authentication](https://docs.microsoft.com/en-us/azure/key-vault/service-to-service-authentication).
+The library we'll use to get our Service Managed token is [Microsoft.Azure.Services.AppAuthentication](https://www.nuget.org/packages/Microsoft.Azure.Services.AppAuthentication). You can find other ways to get the token and more information about the Microsoft.Azure.Service.AppAuthentication library by reading up on  [Service To Service Authentication](https://docs.microsoft.com/en-us/azure/key-vault/service-to-service-authentication).
 
 
 ```csharp
@@ -188,7 +186,7 @@ namespace SummarizationService
 You are now ready to [deploy your Azure Function.](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-csharp#publish-the-project-to-azure) 
 
 > [!IMPORTANT] 
-> If you want to [assign the **Cosmos DB Account Reader**](#Grant-the-System-Identity-Access-to-your-Cosmos-DB.), you will need to use the read only [List Keys api](https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListReadOnlyKeys). This would only populate the read only keys on the DatabaseAccountListKeysResult class.
+> If you want to [assign the **Cosmos DB Account Reader**](#Grant-the-System-Identity-Access-to-your-Cosmos-DB.) role, you will need to use the read only [List Keys api](https://docs.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListReadOnlyKeys). This would only populate the read only keys on the DatabaseAccountListKeysResult class.
 
 ## Next steps