Skip to content

api-management-howto-mutual-certificates.md

Latest commit

 

History

History
117 lines (79 loc) · 7.95 KB

api-management-howto-mutual-certificates.md

File metadata and controls

117 lines (79 loc) · 7.95 KB
title Secure API Management Backend Using Client Certificate Authentication
titleSuffix 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 03/31/2026
ms.author danlep
ms.custom
devx-track-azurepowershell
engagement-fy23
sfi-image-nochange

Secure backend services by using client certificate authentication in Azure API Management

[!INCLUDE api-management-availability-all-tiers]

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 by using the API Management REST API.

Certificate options

API Management provides two options for managing certificates that are used to secure access to backend services:

  • Reference a certificate that's managed in Azure Key Vault.
  • Add a certificate file directly in API Management.

[!INCLUDE api-management-workspace-key-vault-availability]

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 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]

  • If you haven't created an API Management instance yet, see Create an API Management service instance.

  • 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.

  • 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 and your API Management instance is in one of the classic tiers, disable certificate chain validation. See Disable certificate chain validation for self-signed certificates later in this article.

    [!NOTE] When a client certificate is used by API Management for outbound authentication (for example, when API Management presents the certificate to a backend service), you don't need to upload the root or intermediate CA certificates to the API Management CA store. In this scenario, API Management presents the client certificate and doesn't perform certificate chain validation.

    Uploading trusted root or intermediate CA certificates is only required when API Management must validate a certificate chain, such as during inbound client certificate authentication.

[!INCLUDE api-management-client-certificate-key-vault]

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

  1. In the Azure portal, go to your API Management instance.

  2. Under APIs, select APIs.

  3. Select an API from the list.

  4. On the Design tab, select the pencil icon in the Backend section.

  5. In Gateway credentials, select Client cert and then select your certificate in the Client certificate list.

  6. 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. 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're using self-signed certificates and your API Management instance is in one of the classic tiers, 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 (for a new backend) or Set-AzApiManagementBackend (for an existing backend) PowerShell cmdlets and set the -SkipCertificateChainValidation parameter to True:

$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.

Delete a client certificate

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, a warning screen appears. To delete the certificate, you must first remove it from any policies that are configured to use it.

Related content