applied suggestions from LAA

Author: dlepow

articles/api-management/api-management-howto-use-managed-service-identity.md

@@ -19,15 +19,15 @@ ms.custom:
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
-This article shows how to create a managed identity for an Azure API Management instance and how to use it to access other resources. A managed identity generated by Microsoft Entra ID enables API Management to easily and securely access other resources that are protected by Microsoft Entra, like Azure Key Vault. Azure manages these identities, so you don't have to provision or rotate any secrets. For more information about managed identities, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md)
+This article shows how to create a managed identity for an Azure API Management instance and how to use it to access other resources. By using a managed identity generated by Microsoft Entra ID, API Management can easily and securely access other resources that are protected by Microsoft Entra, like Azure Key Vault. Azure manages these identities, so you don't have to provision or rotate any secrets. For more information about managed identities, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md)
 
 You can grant two types of identities to an API Management instance:
 
 - A *system-assigned identity* is tied to your service and is deleted if your service is deleted. The service can have only one system-assigned identity.
-- A *user-assigned identity* is a standalone Azure resource that can be assigned to your service. The service can have multiple user-assigned identities.
+- A *user-assigned identity* is a standalone Azure resource that you can assign to your service. The service can have multiple user-assigned identities.
 
 > [!NOTE]
-> - Managed identities are specific to the Microsoft Entra tenant in which your Azure subscription is hosted. They don't get updated if a subscription is moved to a different directory. If a subscription is moved, you need to recreate and reconfigure the identities.  
+> - Managed identities are specific to the Microsoft Entra tenant in which your Azure subscription is hosted. They don't get updated if you move a subscription to a different directory. If you move a subscription, you need to recreate and reconfigure the identities.  
 > - API Management managed identities are also specific to the Azure subscription in which the service is hosted. If you move the service to a different subscription in the same tenant, you need to recreate and reconfigure the identities.
 
 [!INCLUDE [api-management-workspace-availability](../../includes/api-management-workspace-availability.md)]
@@ -36,7 +36,9 @@ You can grant two types of identities to an API Management instance:
 
 ### Azure portal
 
-To set up a managed identity in the Azure portal, you create an API Management instance and then enable the feature.
+In the Azure portal, you can enable a system-assigned managed identity when you create an API Management instance, or you can create an API Management instance and then enable the feature.
+
+To enable a managed identity in an existing instance:
 
 1. Create an API Management instance in the portal as you normally would. Go to it in the portal.
 1. In the left menu, under **Security**, select **Managed identities**.
@@ -84,7 +86,7 @@ You can create an API Management instance with a system-assigned identity by inc
 
 This property instructs Azure to create and manage the identity for your API Management instance.
 
-For example, a complete ARM template might look like this one:
+For example, a complete ARM template might look like the following example:
 
 ```json
 {
@@ -128,34 +130,34 @@ The `tenantId` property identifies which Microsoft Entra tenant the identity bel
 
 ## Configure Key Vault access by using a managed identity
 
-The following configurations are required if you want to use API Management to access certificates from an Azure key vault.
+To use API Management to access certificates from an Azure key vault, configure the following settings.
 
 [!INCLUDE [api-management-key-vault-certificate-access](../../includes/api-management-key-vault-certificate-access.md)]
 
 [!INCLUDE [api-management-key-vault-network](../../includes/api-management-key-vault-network.md)]
 
 ## Supported scenarios that use system-assigned identity
 
-Following are some common scenarios for using a system-assigned managed identity in Azure API Management.
+The following list shows some common scenarios for using a system-assigned managed identity in Azure API Management.
 
 ### Obtain a custom TLS/SSL certificate for the API Management instance from Key Vault
 
-You can use the system-assigned identity of an API Management instance to retrieve custom TLS/SSL certificates that are stored in Key Vault. You can then assign these certificates to custom domains in the API Management instance. Take these considerations into account:
+You can use the system-assigned identity of an API Management instance to retrieve custom TLS/SSL certificates that are stored in Key Vault. You can then assign these certificates to custom domains in the API Management instance. Consider the following points:
 
 - The content type of the secret must be *application/x-pkcs12*. For more information, see [Domain certificate options](configure-custom-domain.md?tabs=key-vault#domain-certificate-options).
 - You must use the Key Vault certificate secret endpoint, which contains the secret.
 
-> [!Important]
+> [!IMPORTANT]
 > If you don't provide the object version of the certificate, API Management automatically obtains any newer version of the certificate within four hours after it's updated in Key Vault.
 
 The following example shows an ARM template that uses the system-assigned managed identity of an API Management instance to retrieve a custom domain certificate from Key Vault.
 
 #### Prerequisites
 
 * An API Management instance that's configured with a system-assigned managed identity. To create the instance, you can use an [Azure Quickstart Template](https://azure.microsoft.com/resources/templates/api-management-create-with-msi/).
-* A Key Vault instance in the same resource group. The instance must host a certificate that will be used as a custom domain certificate in API Management.
+* A Key Vault instance in the same resource group. The instance must host a certificate that you use as a custom domain certificate in API Management.
 
-The template contains the following steps. 
+The template contains the following steps: 
 
 1. Update the access policies of the Key Vault instance and allow the API Management instance to obtain secrets from it.
 1. Update the API Management instance by setting a custom domain name through the certificate from the Key Vault instance.
@@ -311,11 +313,11 @@ You can use a system-assigned managed identity to access Key Vault to store and
 
 ### Authenticate to a backend by using an API Management identity
 
-You can use the system-assigned identity to authenticate to a backend service via the [authentication-managed-identity](authentication-managed-identity-policy.md) policy.
+Use the system-assigned identity to authenticate to a backend service via the [authentication-managed-identity](authentication-managed-identity-policy.md) policy.
 
 ### Connect to Azure resources behind an IP firewall by using a system-assigned managed identity
 
-API Management is a trusted Microsoft service to the following resources. This trusted status enables the service to connect to the following resources behind a firewall when the firewall enables a setting to **Allow Trusted Microsoft Services to bypass this firewall**. After you explicitly assign the appropriate Azure role to the [system-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md) for a resource instance, the scope of access for the instance corresponds to the Azure role that's assigned to the managed identity.
+API Management is a trusted Microsoft service to the following resources. This trusted status enables the service to connect to the following resources behind a firewall when the firewall enables the **Allow Trusted Microsoft Services to bypass this firewall** setting. After you explicitly assign the appropriate Azure role to the [system-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md) for a resource instance, the scope of access for the instance corresponds to the Azure role that's assigned to the managed identity.
 
 
 - [Trusted access for Key Vault](/azure/key-vault/general/overview-vnet-service-endpoints#trusted-services)
@@ -335,7 +337,7 @@ You can configure and use a system-assigned managed identity to access an event
 
 ### Azure portal
 
-To set up a managed identity in the portal, you must first create an API Management instance and [create a user-assigned identity](../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md). Then complete the following steps.
+To set up a managed identity in the portal, first create an API Management instance and [create a user-assigned identity](../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md). Then complete the following steps.
 
 1. Go to your API Management instance in the portal.
 1. In the left menu, under **Security**, select **Managed identities**.
@@ -394,9 +396,9 @@ You can create an API Management instance that has an identity by including the
 }
 ```
 
-Adding the user-assigned type informs Azure to use the user-assigned identity that's specified for your instance.
+Adding the user-assigned type informs Azure to use the user-assigned identity that you specify for your instance.
 
-For example, a complete ARM template might look like this one:
+For example, a complete ARM template might look like the following example:
 
 ```json
 {
@@ -429,7 +431,7 @@ For example, a complete ARM template might look like this one:
 }
 ```
 
-When the service is created, it has the following additional properties:
+When you create the service, it has the following additional properties:
 
 ```json
 "identity": {
@@ -446,25 +448,25 @@ When the service is created, it has the following additional properties:
 The `principalId` property is a unique identifier for the identity that's used for Microsoft Entra administration. The `clientId` property is a unique identifier for the application's new identity that's used for specifying which identity to use during runtime calls.
 
 > [!NOTE]
-> An API Management instance can have both system-assigned and user-assigned identities. In that scenario, the `type` property would be `SystemAssigned,UserAssigned`.
+> An API Management instance can have both system-assigned and user-assigned identities. In that scenario, the `type` property is `SystemAssigned,UserAssigned`.
 
 ## Supported scenarios that use user-assigned managed identities
 
-Following are some common scenarios for using a user-assigned managed identity in Azure API Management.
+The following list shows some common scenarios for using a user-assigned managed identity in Azure API Management.
 
 ### Obtain a custom TLS/SSL certificate for the API Management instance from Key Vault
 
 You can use a user-assigned identity to establish trust between an API Management instance and Key Vault. This trust can then be used to retrieve custom TLS/SSL certificates that are stored in Key Vault. You can then assign these certificates to custom domains in the API Management instance.
 
 > [!IMPORTANT]
-> If [Key Vault firewall](/azure/key-vault/general/network-security) is enabled on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. For more information, see the section [Requirements for key vault firewall](#requirements-for-key-vault-firewall).
+> If you enable [Key Vault firewall](/azure/key-vault/general/network-security) on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. For more information, see the section [Requirements for key vault firewall](#requirements-for-key-vault-firewall).
 
-Take these considerations into account:
+Consider the following requirements:
 
 - The content type of the secret must be *application/x-pkcs12*.
 - You must use the Key Vault certificate secret endpoint, which contains the secret.
 
-> [!Important]
+> [!IMPORTANT]
 > If you don't provide the object version of the certificate, API Management automatically obtains any newer version of the certificate within four hours after it's updated in Key Vault.
 
 
@@ -473,7 +475,7 @@ Take these considerations into account:
 You can use a user-assigned managed identity to access Key Vault to store and manage secrets for use in API Management policies. For more information, see [Use named values in Azure API Management policies](api-management-howto-properties.md). 
 
 > [!NOTE]
-> If [Key Vault firewall](/azure/key-vault/general/network-security) is enabled on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. For more information, see the section [Requirements for key vault firewall](#requirements-for-key-vault-firewall).
+> If you enable [Key Vault firewall](/azure/key-vault/general/network-security) on your key vault, you can't use a user-assigned identity for access from API Management. You can use the system-assigned identity instead. For more information, see the section [Requirements for key vault firewall](#requirements-for-key-vault-firewall).
 
 ### Authenticate to a backend by using a user-assigned identity
 
@@ -485,9 +487,9 @@ You can configure and use a user-assigned managed identity to access an event hu
 
 ## Remove an identity
 
-You can remove a system-assigned identity by disabling the feature via the portal or an ARM template in the same way that it was created. User-assigned identities can be removed individually. To remove all identities, set the identity type to `"None"`.
+You can remove a system-assigned identity by disabling the feature through the portal or by using an ARM template, just like you created it. You can remove user-assigned identities individually. To remove all identities, set the identity type to `"None"`.
 
-Removing a system-assigned identity in this way also deletes it from Microsoft Entra ID. System-assigned identities are also automatically removed from Microsoft Entra ID when the API Management instance is deleted.
+When you remove a system-assigned identity, you also delete it from Microsoft Entra ID. When you delete the API Management instance, the system-assigned identity is automatically removed from Microsoft Entra ID.
 
 To remove all identities by using an ARM template, update this section:
 
@@ -497,10 +499,10 @@ To remove all identities by using an ARM template, update this section:
 }
 ```
 
-> [!Important]
-> If an API Management instance is configured with a custom SSL certificate from Key Vault and you try to disable a managed identity, the request fails.
+> [!IMPORTANT]
+> If you configure an API Management instance with a custom SSL certificate from Key Vault and try to disable a managed identity, the request fails.
 >
-> You can resolve this by switching from a Key Vault certificate to an inline-encoded certificate and then disabling the managed identity. For more information, see [Configure a custom domain name](configure-custom-domain.md).
+> You can resolve this problem by switching from a Key Vault certificate to an inline-encoded certificate and then disabling the managed identity. For more information, see [Configure a custom domain name](configure-custom-domain.md).
 
 ## Related content