How to secure back-end services using client certificate authentication in Azure API Management
API Management allows to secure access to the back-end service of an API using client certificates. This guide shows how to manage certificates in the Azure API Management service instance in the Azure portal. It also explains how to configure an API to use a certificate to access a back-end service.
For information about managing certificates using the API Management REST API, see Azure API Management REST API Certificate entity.
This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.
This guide shows you how to configure your API Management service instance to use client certificate authentication to access the back-end service for an API. Before following the steps in this article, you should have your back-end service configured for client certificate authentication (to configure certificate authentication in Azure WebSites refer to this article). You need access to the certificate and the password for uploading it to the API Management service.
Follow the steps below to upload a new client certificate. If you have not created an API Management service instance yet, see the tutorial Create an API Management service instance.
- Navigate to your Azure API Management service instance in the Azure portal.
- Select Client certificates from the menu.
- Click the + Add button.
- Browse for the certificate, provide its ID and password.
- Click Create.
The certificate must be in .pfx format. Self-signed certificates are allowed.
Once the certificate is uploaded, it shows in the Client certificates. 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.
To turn off certificate chain validation when using, for example, a self-signed certificate, follow the steps described in this FAQ item.
To delete a certificate, click context menu ... and select Delete beside the certificate.
If the certificate is in use by an API, then a warning screen is displayed. To delete the certificate, you must first remove the certificate from any APIs that are configured to use it.
Click APIs from the API Management menu on the left and navigate to the API.
In the Design tab, click on a pencil icon of the Backend section.
Change the Gateway credentials to Client cert and select your certificate from the dropdown.
This change is effective immediately, and calls to operations of that API will use the certificate to authenticate on the back-end server.
When a certificate is specified for gateway authentication for the back-end service of an API, it becomes part of the policy for that API, and can be viewed in the policy editor.
If you are using self-signed certificates, you will need to disable certificate chain validation in order 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 (for new back end) or
Set-AzApiManagementBackend (for existing back end) PowerShell cmdlets and set the
-SkipCertificateChainValidation parameter to
$context = New-AzApiManagementContext -resourcegroup 'ContosoResourceGroup' -servicename 'ContosoAPIMService' New-AzApiManagementBackend -Context $context -Url 'https://contoso.com/myapi' -Protocol http -SkipCertificateChainValidation $true