Skip to content

Latest commit

 

History

History
111 lines (78 loc) · 7.11 KB

api-management-howto-mutual-certificates.md

File metadata and controls

111 lines (78 loc) · 7.11 KB
title titleSuffix description services documentationcenter author manager editor ms.service ms.workload ms.tgt_pltfrm ms.topic ms.date ms.author
Secure back-end services using client certificate authentication
Azure API Management
Learn how to secure back-end services using client certificate authentication in Azure API Management.
api-management
mikebudzynski
cfowler
api-management
mobile
na
article
01/08/2020
apimpm

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

API Management allows you 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.

Prerequisites

[!INCLUDE updated-for-az]

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 the Azure App Service refer to this article). You need access to the certificate and the password for uploading it to the API Management service.

Upload a Certificate

Note

Instead of an uploaded certificate you can use a certificate stored in the Azure Key Vault service as shown in this example.

Add client certificates

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.

  1. Navigate to your Azure API Management service instance in the Azure portal.
  2. Select Certificates from the menu.
  3. Click the + Add button. Add client certificates
  4. Browse for the certificate, provide its ID and password.
  5. Click Create.

Note

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

Once the certificate is uploaded, it shows in the 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.

Note

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 context menu ... and select Delete beside the certificate.

Delete client certificates

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.

Delete client certificates failure

Configure an API to use a client certificate for gateway authentication

  1. Click APIs from the API Management menu on the left and navigate to the API. Enable client certificates

  2. In the Design tab, click on a pencil icon of the Backend section.

  3. Change the Gateway credentials to Client cert and select your certificate from the dropdown. Enable client certificates

  4. Click Save.

Warning

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

Tip

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.

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

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