Freshness.

Author: TimShererWithAquent

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

@@ -4,14 +4,14 @@ titleSuffix: Azure API Management
 description: Learn how to secure access to APIs by using client certificates. You can use policy expressions to validate incoming certificates.
 services: api-management
 author: dlepow
-
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 10/30/2024
+ms.date: 01/29/2026
 ms.author: danlep
 ms.custom:
   - engagement-fy23
   - sfi-image-nochange
+#customer intent: As a developer using API Management, I want to use client certificates for authentication, including working with Azure Key Vault.
 ---
 
 # How to secure APIs using client certificate authentication in API Management
@@ -28,44 +28,54 @@ For a conceptual overview of API authorization, see [Authentication and authoriz
 
 For certificate validation, API Management can check against certificates managed in your API Management instance. If you choose to use API Management to manage client certificates, you have the following options:
 
-* Reference a certificate managed in [Azure Key Vault](/azure/key-vault/general/overview) 
-* Add a certificate file directly in API Management
+- Reference a certificate managed in [Azure Key Vault](/azure/key-vault/general/overview) 
+- Add a certificate file directly in API Management
 
 [!INCLUDE [api-management-workspace-key-vault-availability](../../includes/api-management-workspace-key-vault-availability.md)]
 
-Using key vault certificates is recommended because it helps improve API Management security:
+We recommend using key vault certificates because the approach helps improve 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
+- You can apply granular [access policies](/azure/key-vault/general/security-features#privileged-access) 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 by using the management REST API.
 
 ## Prerequisites
 
-* If you haven't created an API Management service instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
-* 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 either CER or PFX format. Self-signed certificates are allowed. 
+- If you haven't created an API Management service instance yet, see [Create an API Management service instance](get-started-create-service-instance.md).
+- 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 either CER or PFX format. Self-signed certificates are allowed. 
 
-    If you use a self-signed certificate, also install trusted root and intermediate [CA certificates](api-management-howto-ca-certificates.md) in your API Management instance.
+   If you use a self-signed certificate, also install trusted root and intermediate [CA certificates](api-management-howto-ca-certificates.md) in your API Management instance.
 
-    > [!NOTE]
-    > CA certificates for certificate validation aren't supported in the Consumption tier.
+   > [!NOTE]
+   >
+   > CA certificates for certificate validation aren't supported in the Consumption tier.
 
 [!INCLUDE [api-management-client-certificate-key-vault](../../includes/api-management-client-certificate-key-vault.md)]
 
    > [!NOTE]
-   > If you only wish to use the certificate to authenticate the client with API Management, you can upload a CER file.
+   >
+   > If you only want to use the certificate to authenticate the client with API Management, you can upload a CER file.
 
 ## Enable API Management instance to receive and verify client certificates
 
 ### Developer, Basic, Standard, or Premium tier
 
-To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers, you must enable the **Negotiate client certificate** setting for **Custom domains**.
+To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers, you must enable the **Negotiate client certificate**.
+
+1. Select **Deployment + infrastructure**, then **Custom domains**. 
+1. Select the gateway hostname.
+1. In the **Gateway** pane, select **Negotiate client certificate**.
 
-:::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png" alt-text="Screenshot shows the negotiate client certificate option for a custom domain.":::
+   :::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png" alt-text="Screenshot shows the negotiate client certificate option for a custom domain.":::
 
 ### Consumption, Basic v2, Standard v2, or Premium v2 tier
-To receive and verify client certificates in the Consumption, Basic v2, Standard v2, or Premium v2 tier, you must enable the **Request client certificate** setting for **Custom domains**.
 
-:::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/request-client-certificate.png" alt-text="Screenshot shows the option to request client certificate for custom domains.":::
+To receive and verify client certificates in the Consumption, Basic v2, Standard v2, or Premium v2 tier, you must enable the **Request client certificate**. 
+
+1. Select **Deployment + infrastructure**, then **Custom domains**. 
+1. Under **Client certificates**, enable **Request client certificate**.
+
+   :::image type="content" source="./media/api-management-howto-mutual-certificates-for-clients/request-client-certificate.png" alt-text="Screenshot shows the option to request client certificate for custom domains.":::
 
 ## Policy to validate client certificates
 
@@ -78,16 +88,20 @@ Configure the policy to validate one or more attributes including certificate is
 You can also create policy expressions with the [`context` variable](api-management-policy-expressions.md#ContextVariables) to check client certificates. Examples in the following sections show expressions using the `context.Request.Certificate` property and other `context` properties.
 
 > [!NOTE]
-> Mutual certificate authentication might not function correctly when the API Management gateway endpoint is exposed through the Application Gateway. The Application Gateway functions as a Layer 7 load balancer, establishing a distinct TLS connection with the backend API Management service. The certificate attached by the client in the initial HTTP request isn't forwarded to APIM. However, as a workaround, you can transmit the certificate using the server variables option. For detailed instructions, refer to [Mutual Authentication Server Variables](../application-gateway/rewrite-http-headers-url.md#mutual-authentication-server-variables).
+>
+> Mutual certificate authentication might not function correctly when the API Management gateway endpoint is exposed through the Application Gateway. The Application Gateway functions as a Layer 7 load balancer, establishing a distinct TLS connection with the backend API Management service. The certificate attached by the client in the initial HTTP request isn't forwarded to APIM.
+>
+> As a workaround, you can transmit the certificate using the server variables option. For more information, see [Mutual Authentication Server Variables](../application-gateway/rewrite-http-headers-url.md#mutual-authentication-server-variables).
 
 > [!IMPORTANT]
-> * Starting May 2021, the `context.Request.Certificate` property only requests the certificate when the API Management instance's [`hostnameConfiguration`](/rest/api/apimanagement/current-ga/api-management-service/create-or-update#hostnameconfiguration) sets the `negotiateClientCertificate` property to True. By default, `negotiateClientCertificate` is set to False.
-> * If TLS renegotiation is disabled in your client, you might see TLS errors when requesting the certificate using the `context.Request.Certificate` property. If the errors appear, enable TLS renegotiation settings in the client. 
-> * Certification renegotiation isn't supported in the API Management v2 tiers.
+>
+> - Starting May 2021, the `context.Request.Certificate` property only requests the certificate when the API Management instance's [`hostnameConfiguration`](/rest/api/apimanagement/current-ga/api-management-service/create-or-update#hostnameconfiguration) sets the `negotiateClientCertificate` property to True. By default, `negotiateClientCertificate` is set to False.
+> - If TLS renegotiation is disabled in your client, you might see TLS errors when requesting the certificate using the `context.Request.Certificate` property. If the errors appear, enable TLS renegotiation settings in the client. 
+> - Certification renegotiation isn't supported in the API Management v2 tiers.
 
 ### Checking the issuer and subject
 
-Below policies can be configured to check the issuer and subject of a client certificate:
+The following policies can be configured to check the issuer and subject of a client certificate:
 
 ```xml
 <choose>
@@ -100,13 +114,14 @@ Below policies can be configured to check the issuer and subject of a client cer
 ```
 
 > [!NOTE]
+>
 > To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
 >
 > If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 ### Checking the thumbprint
 
-Below policies can be configured to check the thumbprint of a client certificate:
+The following policies can be configured to check the thumbprint of a client certificate:
 
 ```xml
 <choose>
@@ -119,7 +134,9 @@ Below policies can be configured to check the thumbprint of a client certificate
 ```
 
 > [!NOTE]
+>
 > To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
+>
 > If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 ### Checking a thumbprint against certificates uploaded to API Management
@@ -143,9 +160,10 @@ The following example shows how to check the thumbprint of a client certificate
 > If client certificate is self-signed, root (or intermediate) CA certificates must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
 
 > [!TIP]
-> Client certificate deadlock issue described in this [article](https://techcommunity.microsoft.com/t5/Networking-Blog/HTTPS-Client-Certificate-Request-freezes-when-the-Server-is/ba-p/339672) can manifest itself in several ways, for example, requests freeze, requests result in `403 Forbidden` status code after timing out, `context.Request.Certificate` is `null`. This problem usually affects `POST` and `PUT` requests with content length of approximately 60KB or larger.
 >
-> To prevent this issue from occurring, turn on "Negotiate client certificate" setting for desired hostnames for "Custom domains" as shown in the first image of this document. This feature isn't available in the Consumption tier.
+> Client certificate deadlock issue described in this [article](https://techcommunity.microsoft.com/t5/Networking-Blog/HTTPS-Client-Certificate-Request-freezes-when-the-Server-is/ba-p/339672) can manifest itself in several ways. For example, you might see requests freeze, requests result in `403 Forbidden` status code after timing out, or `context.Request.Certificate` is `null`. This problem usually affects `POST` and `PUT` requests with content length of approximately 60KB or larger.
+>
+> To prevent this issue from occurring, turn on **Negotiate client certificate** setting for desired hostnames for **Custom domains** as shown previously in this article. This feature isn't available in the Consumption tier.
 
 ## Related content
 

articles/api-management/media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png

@@ -11,22 +11,29 @@ ms.author: danlep
 
 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. API Management supports trusted service connectivity to access the key vault for control-plane options.
+- 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. You must 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).
+  1. In your key vault, select **Settings** > **Networking**.
+  1. Under **Firewalls and virtual networks**, select **Allow public access from specific virtual networks and IP addresses**.
+  1. Under **Exception**, select **Allow trusted Microsoft services to bypass this firewall**.
 
-    After completing the configuration, you can block your client address in the key vault firewall.
+  API Management supports trusted service connectivity to access the key vault for control-plane options.
+
+- Ensure that your local client IP address is allowed to access the key vault temporarily. You must 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 you complete the configuration, you can block your client address in the key vault firewall.
 
 > [!IMPORTANT]
+>
 > Starting March 2026, trusted service connectivity to Azure services from the API Management gateway by enabling the **Allow Trusted Microsoft Services to bypass this firewall** firewall setting aren't supported. To continue accessing these services from the API Management gateway after this change, ensure that you choose a different supported network access option. For control-plane operations, you can continue to use trusted service connectivity. [Learn more](../articles/api-management/breaking-changes/trusted-service-connectivity-retirement-march-2026.md).
 
 #### 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 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).
+- 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 API Management in a virtual network](../articles/api-management/virtual-network-reference.md).
+For more information, see [Network configuration when setting up API Management in a virtual network](../articles/api-management/virtual-network-reference.md).