Merge pull request #223997 from MicrosoftDocs/main

Publish to live, Sunday 4 AM PST, 1/15

Author: ttorble

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

@@ -5,33 +5,57 @@ description: Learn how to secure access to APIs by using client certificates. Yo
 services: api-management
 documentationcenter: ''
 author: dlepow
-manager: erikre
-editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 06/01/2021
+ms.date: 01/12/2023
 ms.author: danlep
+ms.custom: engagement-fy23
 ---
 
 # How to secure APIs using client certificate authentication in API Management
 
-API Management provides the capability to secure access to APIs (i.e., client to API Management) using client certificates. You can validate certificates presented by the connecting client and check certificate properties against desired values using policy expressions.
+API Management provides the capability to secure access to APIs (that is, client to API Management) using client certificates and mutual TLS authentication. You can validate certificates presented by the connecting client and check certificate properties against desired values using policy expressions.
 
-For information about securing access to the back-end service of an API using client certificates (i.e., API Management to backend), see [How to secure back-end services using client certificate authentication](./api-management-howto-mutual-certificates.md).
+For information about securing access to the backend service of an API using client certificates (that is, API Management to backend), see [How to secure back-end services using client certificate authentication](./api-management-howto-mutual-certificates.md).
 
 For a conceptual overview of API authorization, see [Authentication and authorization in API Management](authentication-authorization-overview.md#gateway-data-plane). 
 
+## Certificate options
 
-> [!IMPORTANT]
-> To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers you must turn on the "Negotiate client certificate" setting on the "Custom domains" blade as shown below.
+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](../key-vault/general/overview.md) 
+* Add a certificate file directly in API Management
+
+Using key vault certificates is recommended because it helps improve API Management security:
+
+* Certificates stored in key vaults can be reused across services
+* Granular [access policies](../key-vault/general/security-features.md#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.
+
+## Prerequisites
+
+* 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 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 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 are not supported in the Consumption tier.
+
+[!INCLUDE [api-management-client-certificate-key-vault](../../includes/api-management-client-certificate-key-vault.md)]
+
+## 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 on the **Custom domain** blade as shown below.
 
 ![Negotiate client certificate](./media/api-management-howto-mutual-certificates-for-clients/negotiate-client-certificate.png)
 
-> [!IMPORTANT]
-> To receive and verify client certificates in the Consumption tier you must turn on the "Request client certificate" setting on the "Custom domains" blade as shown below.
+### Consumption tier
+To receive and verify client certificates in the Consumption tier, you must enable the **Request client certificate** setting on the **Custom domains** blade as shown below.
 
 ![Request client certificate](./media/api-management-howto-mutual-certificates-for-clients/request-client-certificate.png)
 
@@ -41,8 +65,6 @@ Use the [validate-client-certificate](validate-client-certificate-policy.md) pol
 
 Configure the policy to validate one or more attributes including certificate issuer, subject, thumbprint, whether the certificate is validated against online revocation list, and others.
 
-For more information, see [API Management access restriction policies](api-management-access-restriction-policies.md).
-
 ## Certificate validation with context variables
 
 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.
@@ -66,7 +88,7 @@ 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()`.
+> 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 certificate(s) 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
@@ -84,7 +106,7 @@ 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()`.
+> 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 certificate(s) 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
@@ -103,7 +125,7 @@ The following example shows how 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()`.
+> 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 certificate(s) 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]
@@ -112,5 +134,6 @@ The following example shows how to check the thumbprint of a client certificate
 
 ## Next steps
 
--   [How to secure back-end services using client certificate authentication](./api-management-howto-mutual-certificates.md)
--   [How to upload certificates](./api-management-howto-mutual-certificates.md)
+-   [How to secure backend services using client certificate authentication](./api-management-howto-mutual-certificates.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)

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

@@ -8,14 +8,14 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 01/26/2021
+ms.date: 01/12/2023
 ms.author: danlep 
-ms.custom: devx-track-azurepowershell
+ms.custom: devx-track-azurepowershell, engagement-fy23
 ---
 
 # Secure backend services using client certificate authentication in Azure API Management
 
-API Management allows you to secure access to the backend service of an API using client certificates. 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 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.
 
 You can also manage API Management certificates using the [API Management REST API](/rest/api/apimanagement/current-ga/certificate).
 
@@ -36,73 +36,21 @@ Using key vault certificates is recommended because it helps improve API Managem
 
 [!INCLUDE [updated-for-az](../../includes/updated-for-az.md)]
 
-* If you have not created an API Management service instance yet, see [Create an API Management service instance][Create an API Management service instance].
+* 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.
+* 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. 
 
-### Prerequisites for key vault integration
-
-1. For steps to create a key vault, see [Quickstart: Create a key vault using the Azure portal](../key-vault/general/quick-create-portal.md).
-1. Enable a system-assigned or user-assigned [managed identity](api-management-howto-use-managed-service-identity.md) in the API Management instance.
-1. Assign a [key vault access policy](../key-vault/general/assign-access-policy-portal.md) to the managed identity with permissions to get and list secrets from the vault. To add the policy:
-    1. In the portal, navigate to your key vault.
-    1. Select **Settings > Access policies > + Add Access Policy**.
-    1. Select **Secret permissions**, then select **Get** and **List**.
-    1. In **Select principal**, select the resource name of your managed identity. If you're using a system-assigned identity, the principal is the name of your API Management instance.
-1. Create or import a certificate to the key vault. See [Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal](../key-vault/certificates/quick-create-portal.md).
-1. When adding a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.
-
-[!INCLUDE [api-management-key-vault-network](../../includes/api-management-key-vault-network.md)]
-
-## Add a key vault certificate
-
-See [Prerequisites for key vault integration](#prerequisites-for-key-vault-integration).
-
-> [!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.
-
-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. Under **Security**, select **Certificates**.
-1. Select **Certificates** > **+ Add**.
-1. In **Id**, enter a name of your choice.
-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](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.
-1. Select **Add**.
-
-
-
-    :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Add key vault certificate":::
+    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. 
 
-1. Select **Save**.
-
-## Upload a certificate
-
-To upload a client certificate to API Management: 
+        > [!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)
 
-1. In the [Azure portal](https://portal.azure.com), navigate 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 **Certificate**, select **Custom**.
-1. Browse to select the certificate .pfx file, and enter its password.
-1. Select **Add**.
-
-    :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-add.png" alt-text="Upload client certificate":::
-
-
-1. Select **Save**.
+[!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).
 
-> [!NOTE]
-> To turn off certificate chain validation when using, for example, a self-signed certificate, follow the steps described in [Self-signed certificates](#self-signed-certificates), later in this article.
 
 ## Configure an API to use client certificate for gateway authentication
 
@@ -121,7 +69,7 @@ After the certificate is uploaded, it shows in the **Certificates** window. If y
 > [!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.
 
-## Self-signed certificates
+## 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`.
 
@@ -144,6 +92,7 @@ To delete a certificate, select it and then select **Delete** from the context m
 ## Next steps
 
 * [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)