updates per docs

Author: j-patrick

articles/cosmos-db/TOC.yml

@@ -1010,6 +1010,8 @@
         href: how-to-configure-cross-origin-resource-sharing.md
       - name: Secure Azure Cosmos keys using Key Vault
         href: access-secrets-from-keyvault.md
+      - name: Secure Azure Cosmos Keys using Managed Identity
+        href: managed-identity-based-authentication.md
       - name: Certificate-based authentication with Azure AD
         href: certificate-based-authentication.md
       - name: Restrict user access to data operations only

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

@@ -1,6 +1,6 @@
 ---
-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.
+title: System-Assigned Managed Identity based key access using Azure Active Directory
+description: Learn how to configure an Azure AD system-assigned managed identity to access keys from Azure Cosmos DB.
 author: j-patrick
 ms.service: cosmos-db
 ms.topic: conceptual
@@ -10,33 +10,33 @@ ms.reviewer: sngun
 
 ---
 
-# Managed Identity based authentication and authorization with Azure Cosmos DB and Azure Active Directory
+# System-Assigned Managed Identity based key access using Azure Active Directory
 
 In this article we'll setup a **robust, key rotation agnostic,** solution for Cosmos DB key management by leveraging [Managed Service Identities](../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](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md). 
 
 You'll learn how to:
 
-* Assign a System Identity
-* Grant the System Identity access to your Cosmos DB
+* Assign a System-Assigned Managed Identity
+* Grant the System-Assigned Managed Identity access to your Cosmos DB
 * Write the code for robust Cosmos DB key management
 
 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.
 
-## Assign a System Identity to an Azure Function
+## Assign a System-Assigned Managed Identity to an Azure Function
 
-In this step, you'll assign a managed system identity to your Azure Function.
+In this step, you'll assign a system-assigned managed 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**, 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)
+![System Identity turned on](./media/managed-identity-based-authentication/identity-tab-system-managed-on.png)
 
-## Grant the System Identity Access to your Cosmos DB 
+## Grant the System-Assigned Managed Identity Access to your Cosmos DB 
 
-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:
+In this step, you'll assign a role to the Azure Function's System-Assigned Managed 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**  |
 |---------|---------|
@@ -47,7 +47,7 @@ In this step, you'll assign a role to the Azure Function's System Identity. Cosm
 > 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 about the importance of **least privilege access,** see [lower exposure of privileged accounts](../security/fundamentals/identity-management-best-practices.md#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 Managed Identity to **Cosmos DB Account Reader**. For more information about the importance of **least privilege access,** see [lower exposure of privileged accounts](../security/fundamentals/identity-management-best-practices.md#lower-exposure-of-privileged-accounts).
 
 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. 
 
@@ -61,15 +61,15 @@ For our scenario, we'll read the sale receipt documents, summarize them, and the
 ![Add Role Assignment Pane](./media/managed-identity-based-authentication/cosmos-db-iam-tab-add-role-pane.png)
 
      * **Role** - Select **DocumentDB Account Contributor**
-     * **Assign access to** - Under the Select **System assigned managed identity** subsection, select  **Function App**.
-    * **Select** - The pane will be populated with all the function apps, in your subscription, that have a **System Managed Identity**. In our case I select the **SummaryService** function app: 
+     * **Assign access to** - Under the Select **System-assigned managed identity** subsection, select  **Function App**.
+    * **Select** - The pane will be populated with all the function apps, in your subscription, that have a **Managed System Identity**. In our case I select the **SummaryService** function app: 
 ![Selection of Function App](./media/managed-identity-based-authentication/cosmos-db-iam-tab-add-role-pane-filled.png)
 
 1. Select the function app and click **Save**.
 
 ## 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 **Function App** code below will get the needed Cosmos DB Keys, create a CosmosClient, and run the summarization business logic.
+Now we have a function app that has a system-assigned 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.
 
 We'll be using to get the Cosmos DB Keys is the [List Keys API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListKeys).
 
@@ -88,7 +88,7 @@ namespace SummarizationService
 }
 ```
 
-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](../key-vault/service-to-service-authentication.md).
+The library we'll use to get our System-Assigned Managed Identity 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](../key-vault/service-to-service-authentication.md).
 
 
 ```csharp
@@ -186,7 +186,7 @@ namespace SummarizationService
 You are now ready to [deploy your Azure Function.](../azure-functions/functions-create-first-function-vs-code.md) 
 
 > [!IMPORTANT] 
-> 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/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-assigned-managed-identity-access-to-your-cosmos-db) role, you will need to use the read only [List Keys api](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/DatabaseAccounts/ListReadOnlyKeys). This would only populate the read only keys on the DatabaseAccountListKeysResult class.
 
 ## Next steps