How to secure back-end services using client certificate authentication in Azure API Management

API Management provides the capability to secure access to the back-end service of an API using client certificates. This guide shows how to manage certificates in the API publisher portal, and how to configure an API to use a certificate to access its back-end service.

For information about managing certificates using the API Management REST API, see Azure API Management REST API Certificate entity.

Prerequisites

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 topic, you should have your back-end service configured for client certificate authentication (to configure certificate authentication in Azure WebSites refer to this article), and have access to the certificate and the password for the certificate for uploading in the API Management publisher portal.

Upload a client certificate

To get started, click Publisher portal in the Azure Portal for your API Management service. This takes you to the API Management publisher portal.

API Publisher portal

If you have not yet created an API Management service instance, see Create an API Management service instance in the Get started with Azure API Management tutorial.

Click Security from the API Management menu on the left, and click Client certificates.

Client certificates

To upload a new certificate, click Upload certificate.

Upload certificate

Browse to your certificate, and then enter the password for the certificate.

The certificate must be in .pfx format. Self-signed certificates are allowed.

Upload certificate

Click Upload to upload the certificate.

The certificate password is validated at this time. If it is incorrect an error message is displayed.

Certificate uploaded

Once the certificate is uploaded, it appears on the Client certificates tab. If you have multiple certificates, make a note of the subject, or the last four characters of the thumbprint, which are used to select the certificate when configuring an API to use certificates, as covered in the following Configure an API to use a client certificate for gateway authentication section.

To turn off certificate chain validation when using, for example, a self-signed certificate, follow the steps described in this FAQ item.

Delete a client certificate

To delete a certificate, click Delete beside the desired certificate.

Delete certificate

Click Yes, delete it to confirm.

Confirm delete

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.

Confirm delete

Configure an API to use a client certificate for gateway authentication

Click APIs from the API Management menu on the left, click the name of the desired API, and click the Security tab.

API security

Select Client certificates from the With credentials drop-down list.

Client certificates

Select the desired certificate from the Client certificate drop-down list. If there are multiple certificates you can look at the subject or the last four characters of the thumbprint as noted in the previous section to determine the correct certificate.

Select certificate

Click Save to save the configuration change to the API.

This change is effective immediately, and calls to operations of that API will use the certificate to authenticate on the back-end server.

Save API changes

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.

Certificate policy

Self-signed certificates

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-AzureRmApiManagementBackend (for new back end) or Set-AzureRmApiManagementBackend (for existing back end) PowerShell cmdlets and set the -SkipCertificateChainValidation parameter to True.

$context = New-AzureRmApiManagementContext -resourcegroup 'ContosoResourceGroup' -servicename 'ContosoAPIMService'
New-AzureRmApiManagementBackend -Context  $context -Url 'https://contoso.com/myapi' -Protocol http -SkipCertificateChainValidation $true

Next steps

For more information on other ways to secure your backend service, such as HTTP basic or shared secret authentication, see the following video.