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.

You can also manage API Management certificates using the API Management REST API.

Certificate options

API Management provides two options to manage certificates used to secure access to backend services:

  • Reference a certificate managed in Azure Key Vault
  • 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 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

Note

This article has been updated to use the Azure Az PowerShell module. The Az PowerShell module is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

  • If you have not created an API Management service instance yet, see Create an API Management service instance.
  • You should have your backend 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 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.
  2. Enable a system-assigned or user-assigned managed identity in the API Management instance.
  3. Assign a key vault access policy to the managed identity with permissions to get and list certificates from the vault. To add the policy:
    1. In the portal, navigate to your key vault.
    2. Select Settings > Access policies > + Add Access Policy.
    3. Select Certificate permissions, then select Get and List.
    4. 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.
  4. Create or import a certificate to the key vault. See Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal.

Requirements for Key Vault firewall

If Key Vault firewall is enabled on your key vault, the following are additional requirements:

  • You must use the API Management instance's system-assigned managed identity to access the key vault.
  • In Key Vault firewall, enable the Allow Trusted Microsoft Services to bypass this firewall option.

Virtual network requirements

If the API Management instance is deployed in a virtual network, also configure the following network settings:

  • Enable a service endpoint to Azure Key Vault on the API Management subnet.
  • Configure a network security group (NSG) rule to allow outbound traffic to the AzureKeyVault and AzureActiveDirectory service tags.

For details, see network configuration details in Connect to a virtual network.

Add a key vault certificate

See 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, navigate to your API Management instance.

  2. Under Security, select Certificates.

  3. Select Certificates > + Add.

  4. In Id, enter a name of your choice.

  5. In Certificate, select Key vault.

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

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

    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.

  8. Select Add.

    Add key vault certificate

Upload a certificate

To upload a client certificate to API Management:

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

  2. Under Security, select Certificates.

  3. Select Certificates > + Add.

  4. In Id, enter a name of your choice.

  5. In Certificate, select Custom.

  6. Browse to select the certificate .pfx file, and enter its password.

  7. Select Add.

    Upload client certificate

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.

Note

To turn off certificate chain validation when using, for example, a self-signed certificate, follow the steps described in Self-signed certificates, later in this article.

Configure an API to use client certificate for gateway authentication

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

  2. Under APIs, select APIs.

  3. Select an API from the list.

  4. In the Design tab, select the editor icon in the Backend section.

  5. In Gateway credentials, select Client cert and select your certificate from the dropdown.

  6. Select Save.

    Use client certificate for gateway authentication

Caution

This change is effective immediately, and calls to operations of that 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.

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 (for new backend) or Set-AzApiManagementBackend (for existing backend) 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

Delete a client certificate

To delete a certificate, select it and then select Delete from the context menu (...).

Delete a certificate

Important

If the certificate is referenced by any policies, then a warning screen is displayed. To delete the certificate, you must first remove the certificate from any policies that are configured to use it.

Next steps