Merge pull request #299867 from v-albemi/client-certificates

Freshness Edit: Azure API Management

Author: Stacyrch140

articles/api-management/api-management-howto-mutual-certificates.md

@@ -1,101 +1,103 @@
 ---
-title: Secure API Management backend using client certificate authentication
+title: Secure API Management Backend Using Client Certificate Authentication
 titleSuffix: Azure API Management
-description: Learn how to manage client certificates and secure backend services using client certificate authentication in Azure API Management.
+description: Learn how to manage client certificates and secure backend services by using client certificate authentication in Azure API Management.
 services: api-management
 author: dlepow
 
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 01/12/2023
+ms.date: 05/19/2025
 ms.author: danlep 
 ms.custom: devx-track-azurepowershell, engagement-fy23
+
+#customer intent: As an API developer, I want to secure backend services by using client certificate authentication. 
 ---
 
-# Secure backend services using client certificate authentication in Azure API Management
+# Secure backend services by using client certificate authentication in Azure API Management
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
 
-API Management allows you to secure access to the backend service of an API using client certificates and mutual TLS authentication. This guide shows how to manage certificates in an Azure API Management service instance using the Azure portal. It also explains how to configure an API to use a certificate to access a backend service.
+API Management allows you to secure access to the backend service of an API by using client certificates and mutual TLS authentication. This article shows how to manage certificates in API Management by using the Azure portal. It also explains how to configure an API to use a certificate to access a backend service.
 
-You can also manage API Management certificates using the [API Management REST API](/rest/api/apimanagement/current-ga/certificate).
+You can also manage API Management certificates by using the [API Management REST API](/rest/api/apimanagement/current-ga/certificate).
 
 ## Certificate options
 
-API Management provides two options to manage certificates used to secure access to backend services:
+API Management provides two options for managing certificates that are used to secure access to backend services:
 
-* Reference a certificate managed in [Azure Key Vault](/azure/key-vault/general/overview) 
-* Add a certificate file directly in API Management
+* Reference a certificate that's managed in [Azure Key Vault](/azure/key-vault/general/overview). 
+* Add a certificate file directly in API Management.
 
-Using key vault certificates is recommended because it helps improve API Management security:
+We recommend that you use key vault certificates because doing so improves API Management security:
 
-* Certificates stored in key vaults can be reused across services
-* Granular [access policies](/azure/key-vault/general/security-features#privileged-access) can be applied to certificates stored in key vaults
-* Certificates updated in the key vault are automatically rotated in API Management. After update in the key vault, a certificate in API Management is updated within 4 hours. You can also manually refresh the certificate using the Azure portal or via the management REST API.
+* Certificates stored in key vaults can be reused across services.
+* Granular [access policies](/azure/key-vault/general/security-features#privileged-access) can be applied to certificates stored in key vaults.
+* Certificates updated in the key vault are automatically rotated in API Management. After an update in the key vault, a certificate in API Management is updated within four hours. You can also manually refresh the certificate by using the Azure portal or via the management REST API.
 
 ## Prerequisites
 
 [!INCLUDE [updated-for-az](~/reusable-content/ce-skilling/azure/includes/updated-for-az.md)]
 
-* If you have not created an API Management service instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
-* You should have your backend service configured for client certificate authentication. To configure certificate authentication in the Azure App Service, refer to [this article][to configure certificate authentication in Azure WebSites refer to this article]. 
-* You need access to the certificate and the password for management in an Azure key vault or upload to the API Management service. The certificate must be in **PFX** format. Self-signed certificates are allowed. 
+* If you haven't created an API Management instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
+* Configure your backend service client certificate authentication. For information about configuring certificate authentication in Azure App Service, see [Configure TLS mutual authentication in App Service][to configure certificate authentication in Azure WebSites refer to this article]. 
+* Ensure that you have access to the certificate and the password for management in an Azure key vault, or a certificate to upload to the API Management service. The certificate must be in PFX format. Self-signed certificates are allowed. 
 
     If you use a self-signed certificate:
     * Install trusted root and intermediate [CA certificates](api-management-howto-ca-certificates.md) in your API Management instance. 
 
         > [!NOTE]
-        > CA certificates for certificate validation are not supported in the Consumption tier.
-    * [Disable certificate chain validation](#disable-certificate-chain-validation-for-self-signed-certificates)
+        > CA certificates for certificate validation aren't supported in the Consumption tier.
+    * Disable certificate chain validation. See [Disable certificate chain validation for self-signed certificates](#disable-certificate-chain-validation-for-self-signed-certificates) later in this article.
 
 [!INCLUDE [api-management-client-certificate-key-vault](../../includes/api-management-client-certificate-key-vault.md)]
 
-After the certificate is uploaded, it shows in the **Certificates** window. If you have many certificates, make a note of the thumbprint of the desired certificate in order to configure an API to use a client certificate for [gateway authentication](#configure-an-api-to-use-client-certificate-for-gateway-authentication).
+After the certificate is uploaded, it shows in the **Certificates** window. If you have many certificates, note the thumbprint of the certificate that you just uploaded. You'll need it to configure an API to use the client certificate for [gateway authentication](#configure-an-api-to-use-client-certificate-for-gateway-authentication).
 
 
 ## Configure an API to use client certificate for gateway authentication
 
-1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
 1. Under **APIs**, select **APIs**.
 1. Select an API from the list. 
-1. In the **Design** tab, select the editor icon in the **Backend** section.
-1. In **Gateway credentials**, select **Client cert** and select your certificate from the dropdown.
+1. On the **Design** tab, select the pencil icon in the **Backend** section.
+1. In **Gateway credentials**, select **Client cert** and then select your certificate in the **Client certificate** list.
 1. Select **Save**.
 
     :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-enable-select.png" alt-text="Use client certificate for gateway authentication":::
 
 > [!CAUTION]
-> This change is effective immediately, and calls to operations of that API will use the certificate to authenticate on the backend server.
+> This change is effective immediately. Calls to operations of the API will use the certificate to authenticate on the backend server.
 
 > [!TIP]
 > When a certificate is specified for gateway authentication for the backend service of an API, it becomes part of the policy for that API and can be viewed in the policy editor.
 
 ## Disable certificate chain validation for self-signed certificates
 
-If you are using self-signed certificates, you will need to disable certificate chain validation for API Management to communicate with the backend system. Otherwise it will return a 500 error code. To configure this, you can use the [`New-AzApiManagementBackend`](/powershell/module/az.apimanagement/new-azapimanagementbackend) (for new backend) or [`Set-AzApiManagementBackend`](/powershell/module/az.apimanagement/set-azapimanagementbackend) (for existing backend) PowerShell cmdlets and set the `-SkipCertificateChainValidation` parameter to `True`.
+If you're using self-signed certificates, you need to disable certificate chain validation to enable API Management to communicate with the backend system. Otherwise you'll get a 500 error code. To disable this validation, you can use the [`New-AzApiManagementBackend`](/powershell/module/az.apimanagement/new-azapimanagementbackend) (for a new backend) or [`Set-AzApiManagementBackend`](/powershell/module/az.apimanagement/set-azapimanagementbackend) (for an existing backend) PowerShell cmdlets and set the `-SkipCertificateChainValidation` parameter to `True`:
 
 ```powershell
-$context = New-AzApiManagementContext -resourcegroup 'ContosoResourceGroup' -servicename 'ContosoAPIMService'
+$context = New-AzApiManagementContext -ResourceGroupName 'ContosoResourceGroup' -ServiceName 'ContosoAPIMService'
 New-AzApiManagementBackend -Context  $context -Url 'https://contoso.com/myapi' -Protocol http -SkipCertificateChainValidation $true
 ```
 
 You can also disable certificate chain validation by using the [Backend](/rest/api/apimanagement/current-ga/backend) REST API.
 
 ## Delete a client certificate
 
-To delete a certificate, select it and then select **Delete** from the context menu (**...**).
+To delete a certificate, select **Delete** on the ellipsis (**...**) menu:
 
 :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-delete-new.png" alt-text="Delete a certificate":::
 
 > [!IMPORTANT]
-> If the certificate is referenced by any policies, then a warning screen is displayed. To delete the certificate, you must first remove the certificate from any policies that are configured to use it.
+> If the certificate is referenced by any policies, a warning screen appears. To delete the certificate, you must first remove it from any policies that are configured to use it.
 
 ## Related content
 
 * [How to secure APIs using client certificate authentication in API Management](api-management-howto-mutual-certificates-for-clients.md)
 * [How to add a custom CA certificate in Azure API Management](./api-management-howto-ca-certificates.md)
-* Learn about [policies in API Management](api-management-howto-policies.md)
+* [Policies in API Management](api-management-howto-policies.md)
 
 
 [How to add operations to an API]: ./mock-api-responses.md

articles/api-management/media/api-management-howto-ip-addresses/public-ip.png

@@ -10,55 +10,54 @@ ms.author: danlep
 
 [!INCLUDE [api-management-workspace-availability](api-management-workspace-availability.md)]
 
-1. If you don't already have a key vault, create one. For steps to create a key vault, see [Quickstart: Create a key vault using the Azure portal](/azure/key-vault/general/quick-create-portal).
+1. If you don't already have a key vault, create one. For information about creating a key vault, see [Quickstart: Create a key vault using the Azure portal](/azure/key-vault/general/quick-create-portal).
 
-    To create or import a certificate to the key vault, see [Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal](/azure/key-vault/certificates/quick-create-portal).
-
-1. Enable a system-assigned or user-assigned [managed identity](../articles/api-management/api-management-howto-use-managed-service-identity.md) in the API Management instance.
+    
+1. Enable a system-assigned or user-assigned [managed identity](../articles/api-management/api-management-howto-use-managed-service-identity.md) in API Management.
 
 [!INCLUDE [api-management-key-vault-access](./api-management-key-vault-access.md)]
 
+To create a certificate in the key vault or import a certificate to the key vault, see [Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal](/azure/key-vault/certificates/quick-create-portal).
+
 [!INCLUDE [api-management-key-vault-network](./api-management-key-vault-network.md)]
 
 ## Add a key vault certificate
 
 See [Prerequisites for key vault integration](#prerequisites-for-key-vault-integration).
 
 > [!IMPORTANT]
-> When adding a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.
+> To add a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.
 
 > [!CAUTION]
-> When using a key vault certificate in API Management, be careful not to delete the certificate, key vault, or managed identity used to access the key vault.
+> When using a key vault certificate in API Management, be careful not to delete the certificate, key vault, or managed identity that's used to access the key vault.
 
 To add a key vault certificate to API Management:
 
-1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
 1. Under **Security**, select **Certificates**.
 1. Select **Certificates** > **+ Add**.
-1. In **Id**, enter a name of your choice.
+1. In **Id**, enter a name.
 1. In **Certificate**, select **Key vault**.
 1. Enter the identifier of a key vault certificate, or choose **Select** to select a certificate from a key vault.
     > [!IMPORTANT]
-    > If you enter a key vault certificate identifier yourself, ensure that it doesn't have version information. Otherwise, the certificate won't rotate automatically in API Management after an update in the key vault.
-1. In **Client identity**, select a system-assigned or an existing user-assigned managed identity. Learn how to [add or modify managed identities in your API Management service](../articles/api-management/api-management-howto-use-managed-service-identity.md).
+    > If you enter a key vault certificate identifier yourself, be sure that it doesn't have version information. Otherwise, the certificate won't rotate automatically in API Management after an update in the key vault.
+1. In **Client identity**, select a system-assigned identity or an existing user-assigned managed identity. For more information, see [Use managed identities in Azure API Management](../articles/api-management/api-management-howto-use-managed-service-identity.md).
     > [!NOTE]
-    > The identity needs permissions to get and list certificate from the key vault. If you haven't already configured access to the key vault, API Management prompts you so it can automatically configure the identity with the necessary permissions.
+    > The identity needs to have permissions to get and list certificates from the key vault. If you haven't already configured access to the key vault, API Management prompts you so that it can automatically configure the identity with the necessary permissions.
 1. Select **Add**.
 
-
-
-    :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Screenshot of adding a key vault certificate to API Management in the portal.":::
+    :::image type="content" source="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Screenshot that shows how to add a key vault certificate to API Management in the portal." lightbox="../articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-kv.png":::
 
 1. Select **Save**.
 
 ## Upload a certificate
 
 To upload a client certificate to API Management: 
 
-1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
+1. In the [Azure portal](https://portal.azure.com), go to your API Management instance.
 1. Under **Security**, select **Certificates**.
 1. Select **Certificates** > **+ Add**.
-1. In **Id**, enter a name of your choice.
+1. In **Id**, enter a name.
 1. In **Certificate**, select **Custom**.
 1. Browse to select the certificate .pfx file, and enter its password.
 1. Select **Add**.

articles/api-management/media/api-management-howto-mutual-certificates/apim-client-cert-add.png

@@ -9,19 +9,19 @@ ms.author: danlep
 
 #### Requirements for Key Vault firewall
 
-If [Key Vault firewall](/azure/key-vault/general/network-security) is enabled on your key vault, the following are additional requirements:
+If [Key Vault firewall](/azure/key-vault/general/network-security) is enabled on your key vault, you must meet these requirements:
 
-* You must use the API Management instance's **system-assigned** managed identity to access the key vault.
+* You must use the API Management instance's system-assigned managed identity to access the key vault.
 * In Key Vault firewall, enable the **Allow Trusted Microsoft Services to bypass this firewall** option.
 * Ensure that your local client IP address is allowed to access the key vault temporarily while you select a certificate or secret to add to Azure API Management. For more information, see [Configure Azure Key Vault networking settings](/azure/key-vault/general/how-to-azure-key-vault-network-security).
 
-    After completing the configuration, you may block your client address in the key vault firewall.
+    After completing the configuration, you can block your client address in the key vault firewall.
 
 #### Virtual network requirements
 
 If the API Management instance is deployed in a virtual network, also configure the following network settings:
 
-* Enable a [service endpoint](/azure/key-vault/general/overview-vnet-service-endpoints) to Azure Key Vault on the API Management subnet.
+* Enable a [service endpoint](/azure/key-vault/general/overview-vnet-service-endpoints) to Key Vault on the API Management subnet.
 * Configure a network security group (NSG) rule to allow outbound traffic to the AzureKeyVault and AzureActiveDirectory [service tags](../articles/virtual-network/service-tags-overview.md). 
 
-For details, see [Network configuration when setting up Azure API Management in a VNet](../articles/api-management/virtual-network-reference.md).
+For details, see [Network configuration when setting up API Management in a virtual network](../articles/api-management/virtual-network-reference.md).